dt(1)

📦 version 23.28, in opensuse-leap 16.0

💖 dt 💖

okay so this is the manual page for dt, the Data Test Program — it lives in section 1, General Commands Manual, and bestie, it is a WHOLE journey 🎀 grab a snack.

✨ SYNOPSIS ✨

dt [options]

like, that's it. that's the whole vibe. options go brrr 🌈

💀 EXTREME WARNING!!! 💀

okay so, real talk, no cap: using this program is almost guaranteed to find problems and make your schedules slip. If you're scared of finding bugs, or if you're scared of, like, breaking your system, then please don't use this program for testing. You can pay now or pay later, but you've been warned! 💀

🦋 DESCRIPTION 🦋

dt is a generic data test program — its whole thing is verifying that peripherals and I/O sub-systems actually work the way they're supposed to, and also grabbing performance info while it's at it. And because it literally verifies the data, you can think of dt as a generic diagnostic tool. slay 💅

So the original goal was "be a generic test tool" and honestly? accomplished. But it very quickly became obvious that device-specific tests (terminals, for example) and different programming interfaces — memory mapped files, POSIX asynchronous I/O API's — were necessary, so special options got added to turn those test modes on and to set the parameters they need.

dt command lines are similar to the dd program, which is popular on most UNIX systems. dt has a ton of options so you, the user, control most test parameters, which means customized tests can be written easily and quickly just by specifying simple command line options. And because the exit status of the program always reflects the completion status of a test, scripts can easily detect failures to perform automatic regression tests. scripting girlies, this one's for you 🫶

dt has been used to successfully test disks, tapes, serial lines, parallel lines, pipes & FIFO's, memory mapped files, and POSIX Asynchronous I/O. In fact, dt can be used with any device that supports the standard open, read, write, and close system calls. Some devices need special support — serial lines, for example, need the speed, parity, data bits, etc set up — but dt's design makes adding that setup easy.

Most tests can be initiated by a simple dt command line, and lots of I/O can be initiated quickly using multiple processes and/or POSIX AIO, for those operating systems supporting AIO. More complex tests are normally initiated by writing shell scripts and using dt in conjunction with other tools, such as scu (SCSI Command Utility). Several shell scripts for testing disks, tapes, and serial lines are also supplied with this kit, which can be used as templates for developing other specialized test scripts. templates?? iconic. 👑

Specific system features are now being added to dt so more extensive testing can be accomplished. The program has been restructured to allow easy inclusion of new device specific tests by dispatching to test functions through a function lookup table. This table gets setup automatically, based on options enabled, or via the device type "dtype=" option. auto-setup, we love to see it ✨

WARNING: dt does not perform any sanity checking of the output device specified. This means if you are running as root on Unix and you specify a raw disk device, dt will overwrite existing file systems, so please be careful! I HATE TO ADMIT, I'VE DONE THIS MYSELF! 😭

🖥️ Operating Systems Supported 🖥️

dt is conditionalized to run on AIX, HP-UX, SUN, ULTRIX, OSF, QNX, SCO Unixware, Windows, and Linux operating systems. Porting is simple for OSes with POSIX APIs. 🌈

🎀 Test Uses 🎀

If you've got an imagination, you will find so many uses for dt, but here's a few that have actually been used, just to whet your appetite:

  • Testing of tape devices using different block sizes to determine the best blocking factor for optimum performance and capacity. This is very important for streaming tapes devices. 🎞️
  • Write tapes to end of tape, to determine the total tape capacity. This gives the total data capacity of tapes, after inter-record gaps, preamble/postambles, or pad blocks are written on the tape.
  • Read existing tapes with data comparison disabled, to determine the amount of data on the tape. This is useful to determine how much disk space is required to read in a tape, or to simply verify the tape can be read without errors.
  • Reading/writing an entire tape to ensure device drivers properly sense and handle end of tape error conditions.
  • Write a tape and ensure it can be read on another tape drive to test drive compatibility (also referred to as transportability).
  • Read multiple tape files to ensure file marks and end of tape are reported and handled properly by tape drivers.
  • I/O to disks using the raw device interface, to determine the optimum performance of the controller. This usually gives a good indication of how well the controller cache or read-ahead improves I/O performance for sequential or random file access.
  • I/O to disk files through the file system, to determine the affect the buffer cache has on write and read performance. You must know the characteristics of your O/S's buffer cache to select file sizes to either get optimum performance from the cache, or to defeat the affect of the buffer cache. 🧠
  • Reading/writing of entire disks, to ensure the media capacity and end of media error handling is properly reported by device drivers.
  • Test memory mapped files to compare I/O performance against raw and file system I/O. Typically, memory mapped I/O approaches the raw device performance.
  • Testing I/O to files on NFS mounted file systems. This will give you a good indication of your ethernet performance to remote files. 🌐
  • Writing/reading pipes & FIFO's to verify pipe operation and performance.
  • Initiating multiple processes to test optimizations of buffer cache, device drivers, and/or intelligent controllers. This is also useful to test multiple device access and for loading the I/O sub-system.
  • Force I/O at different memory boundaries to test low level driver handling. Using the align option, you can set memory alignment for testing specialized device driver DMA code. This is very useful when developing new I/O sub-systems. 🔬
  • Do loopback testing of parallel or serial lines on either the same system of different systems. This is a useful compatibility test when running different machines running different operating systems.
  • Enable POSIX Asynchronous I/O to verify proper operation of this API and to determine performance gains (over standard synchronous I/O). This is also useful for queuing multiple I/O requests to drivers and for testing SCSI tag queuing and RAID configurations. 🔥
  • Specify variable record options for testing variable tape devices.
  • On Tru64 cluster systems, distributed lock manager (DLM) options can be used to control access to shared devices or files.
  • Also available on Tru64 UNIX is the ability to use Extended Error Information (EEI) to detect and recover from SCSI bus/device resets (tape is repositioned for continuing the test).
  • Monitor slow or no I/O progress. 👀
  • Execute a trigger when failures occur.

⚙️ Program Options ⚙️

This section describes program options and special notes related to each. The dt help file provides a summary of the options, and the default value of most options. (iykyk — go read the help file too 💜)

📥 Input File if= Option 📥

This option specifies the input file to open for reads. The device is opened read-only, so devices which only permit or support read access — parallel input devices, for example — can be opened successfully. 🫶

Special Notes:

  • Data read is automatically verified with the default data pattern, unless you disable this action via the "disable=compare" option.
  • Extra pad bytes of sizeof(int), are allocated at the end of data buffers, initialized with the inverted data pattern, and then verified after each read request to ensure the end of data buffers didn't get overwritten by file system and/or device drivers. This extra check has found problems with flushing DMA FIFO's on several machines. 💀

Syntax:

if=filename
       The input file to read.

📤 Output File of= Option 📤

This option specifies the output file to open for writes. After the write portion of the test, the device is closed (to reposition to start of file or to rewind the tape), re-opened, and then a read verification pass is performed. If you wish to prevent the read verify pass, you must specify the "disable=verify" option.

Special Notes:

  • Terminal devices are closed between passes so previously set terminal characteristics don't get reset. This also caused a race condition when doing loopback testing with two processes. 😵‍💫
  • When testing terminal (serial) devices, modem control is disabled (via setting CLOCAL) to prevent tests from hanging. If the "enable=modem" option is specified, then CLOCAL is reset, hangup on close HUPCL is set, and testing will not preceed until carrier or DSR is detected. This code is not fully tested, but this description accurately describes the code.
  • At the present time, tapes are rewound by closing the device, so you must specify the rewind device during testing if the read verify pass is being performed. This restriction will probably change in the next release since magtape control commands will be supported (tape specific tests as well).
  • O_CREAT open flag is cleared to prevent accidently creating files in this directory when not specifying the correct device name (very easy to do when running tests as super-user root). 🙈
  • When writing to raw disks on Tru64 UNIX, if the disk was previously labeled, you must issue the "disklabel -z" command to destroy the label block or else you cannot write to this area of this disk (block 0). Failure to do this results in the error "Read-only file system" (errno=EROFS) being returned on write requests.

Syntax:

of=filename
       The output file to write.

🎨 Pattern File pf= Option 🎨

This option specifies a pattern file to use for the data pattern during testing. This option overrides the "pattern=" option and allows you to specify specialized patterns. The only restriction to this option is that the entire file must fit in memory. A buffer is allocated to read the entire pattern file into memory before testing starts, so performance is not affected by reading the pattern file. ✨

Syntax:

pf=filename
       The data pattern file to use.

💾 Block Size bs= Option

okay so bs= sets the block size, in bytes, that dt uses while it's testing. right now it sets both the input and the output block size at the same time. when she originally wrote this program she didn't need separate block sizes, but that might change in a future release where the ibs= and obs= options (you know, the ones dd has) get added back. ✨

Special Notes:

  • when you turn on variable length records with the min= option, this also sets the maximum record size that gets written/read. 🎀
  • for memory mapped files, the block size has to be a multiple of the system dependent page size (normally 4k or 8k bytes).

Syntax:

bs=value
  • bs=value — the block size to read/write. 💅

📝 Log File log[tu]= Options

this one sends all program output to a log file, and the way it does that is by re-opening the standard error stream (stderr) onto the file you name. since every bit of dt's output goes to stderr anyway, library functions like perror() end up writing into that log file too. 🫶

Special Notes

  • a separate buffer gets allocated for the stderr stream, and that stream is set buffered so your timing doesn't get messed up by program output.
  • when you're starting multiple processes with the procs= option, all of the output goes to the same log file. each process's output is tagged with the process ID (PID) as part of the message (errors & statistics).
  • logt=filename will truncate the existing log file.
  • logu=filename will create unique log files when you're running multiple processes (w/pid). 🌈

Syntax:

log[tu]=filename
  • log[tu]=filename — the log file name to write.

special format keywords get expanded when they show up inside the log file name, so you can make unique names for every single test. iconic behavior honestly:

Log File Format Keywords:

  • %iodir — the I/O direction.
  • %iotype — the I/O type.
  • %host — the host name.
  • %pid — the process ID.
  • %user — the user name.

Example:

log=dt_%host_%user_%iodir_%iotype-%pid.log

please go look at the DiskTests.ksh script for examples of how to use this. 📓

⚡ POSIX Asynchronous I/O aios= Option

this option turns on POSIX asynchronous I/O and controls how many requests the program keeps in flight. ⚡

Special Notes

  • the default is to queue up to 8 requests.
  • the system limit for AIO on Tru64 UNIX is dynamic, and you can ask about it with the sysconfig -q rt command.
  • you can use the enable=aio option to enable AIO and just take the default request limit.
  • AIO is only supported for character devices and is disabled for terminals. on Tru64 UNIX you can alter the Makefile and link against libaio.a, which allows AIO with any device/file by mimic'ing AIO using POSIX threads.
  • AIO requests can be cancelled on Tru64 UNIX, so queuing a lot of requests to 1/2in tape devices will probably end with you running off the end of the tape reel 😭 this is not a problem for cartridge tapes though.

Syntax:

aios=value
  • aios=value — set number of AIO's to queue. 🔥

⏰ Keepalive Alarm Time alarm= Option

💬 Keepalive Message *keepalive= Options

these options control a user defined message that gets emitted during the test. you decide how often the keepalive message shows up with the alarm=time option, and you decide the format of the message(s) with the *keepalive=string options. the normal keepalive= option defines the script emitted during the test, while pkeepalive= is the per pass message string, and tkeepalive= is the totals message string (which overrides what dt normally displays). for a full description of the message control strings, see the UserGuide. 👑

Syntax:

alarm=time
keepalive=string
pkeepalive=str
tkeepalive=str
  • alarm=time — the keepalive alarm time.
  • keepalive=string — the keepalive message string.
  • pkeepalive=str — the pass keepalive msg string.
  • tkeepalive=str — the totals keepalive msg string.

🔤 Keepalive Message Format Control

the keepalive string is free format, just like a printf(), and here are the format control strings it understands:

Keepalive Format Control:

  • %b — the bytes read or written.
  • %B — total bytes read and written.
  • %c — record count for this pass.
  • %C — total records for this test.
  • %d — the device name.
  • %D — the real device name.
  • %e — the number of errors.
  • %E — the error limit.
  • %f — the files read or written.
  • %F — total files read and written.
  • %h — the host name.
  • %H — the full host name.
  • %k — the kilobytes this pass.
  • %K — total kilobytes for this test.
  • %l — blocks read or written.
  • %L — total blocks read and written.
  • %m — the megabytes this pass.
  • %M — total megabytes for this test.
  • %p — the pass count.
  • %P — the pass limit.
  • %r — records read this pass.
  • %R — total records read this test.
  • %s — the seconds this pass.
  • %S — the total seconds this test.
  • %t — the pass elapsed time.
  • %T — the total elapsed time.
  • %i — the I/O mode (read/write)
  • %u — the user (login) name.
  • %w — records written this pass.
  • %W — total records written this test.

🚀 Performance Keywords

  • %bps — the bytes per second.
  • %lbps — logical blocks per second.
  • %kbps — kilobytes per second.
  • %mbps — the megabytes per second.
  • %iops — the I/O's per second.
  • %spio — the seconds per I/O.

lowercase means per pass stats, uppercase means total stats. that's the whole rule bestie, no cap. 💜

Default:

%d Stats: mode %i, blocks %l, %m Mbytes, pass %p/%P, elapsed %t

or, if the pass statistics summary is disabled:

%d Stats: mode %i, blocks %L, %M Mbytes, pass %p/%P, elapsed %T

and here's an example used by Hazards' diskdt process:

keepalive="count = %C; e = %e; t = %S; IOpS = %IOPS; SpIO = %SPIO"
tkeepalive="STAT +RawMbytes %MBPS +RawReads %R +RawWrites %W";

📐 Buffer Alignment align= Option

this option controls the alignment of the data buffer that gets allocated (it's normally page aligned). it's lowkey so useful for testing certain DMA boundary conditions that are not easily reproduced any other way. the rotate option automatically adjust the data buffer pointer by (0, 1, 2, 3, ...) for each I/O request, so all the various boundaries get fully tested. 🎯

Syntax:

align=offset
align=rotate
  • align=offset — set offset within page aligned buffer.
  • align=rotate — rotate data address through sizeof(ptr).

🗑️ File Disposition dispose= Option

this controls the disposition of test files created on file systems. by default the test file that gets created is deleted before exiting, but sometimes you might want to keep it around — to examine it further, to use it as a pattern file, or just to do the read verify pass of another test (for example, reading the file via the memory map API). 🌸

Syntax:

dispose=mode
  • dispose=mode — set file dispose to: {delete, keep, or keeponerror}.

📤 Dump Data Limit dlimit= Option

this lets you specify the dump data limit used when data compare errors happen. the default dump data limit is 64 bytes. 🙈

Syntax:

dlimit=value
  • dlimit=value — sets the data dump limit to value.

📏 Device Size dsize= Option

this lets you specify the device block size that's used. on Tru64 Unix the device block size is obatined automatically by an OS specific IOCTL. for all other systems, random access devices default to 512 byte blocks. you'll likely use this option with C/DVD's, since their default block size to 2048 bytes per block. 💿

Syntax:

dsize=value
  • dsize=value — set the device block (sector) size.

🖥️ Device Type dtype= Option

⌨️ Input Device Type idtype= Option

🎮 Output Device Type odtype= Option

these options are how you inform dt what type of device test is going to be performed. without that knowledge, only generic testing is possible. 🫡

Special Notes

  • on Tru64 UNIX systems these options are not necessary, because that info is obtained via the DECIOCGET or DEVGETINFO IOCTL's.
  • although the program accepts a large number of device types (see the list below), specific tests only exists for "disk", "tape", "fifo", and "terminal" device types. others may be added in the future.
  • in the case of "disk" device type, it reports the relative block number when read, write, or data compare errors occur.
  • also for "disk" devices, it will automatically determine the disk capacity if a data or record limit is not specified. this is done via a series of seek/read requests.
  • on each operating system supported, string compares are done on well known device names to automatically select the device type. for example on QNX, "/dev/hd" for disk, "/dev/tp" for tapes, and "/dev/ser" for serial lines.
  • the device type gets displayed in the total statictics.

Syntax:

dtype=string
idtype=string
odtype=string
  • dtype=string — sets the device type.
  • idtype=string — sets the input device type.
  • odtype=string — sets the output device type.

The Valid Device Types Are:

  • audio
  • comm
  • disk
  • graphics
  • memory
  • mouse
  • network
  • fifo
  • pipe
  • printer
  • processor
  • socket
  • special
  • streams
  • tape
  • terminal
  • unknown
Note: although dt does not provide specific test support for each of the devices shown above, its' design makes it easy to add new device specific tests. specific support exists for disk, fifo, pipe, tape, and terminals. support for "ptys" may be added in the future as well. 🧚

🚨 Error Limit errors= Option

this option controls the maximum number of errors tolerated before the program exits. bestie this is the "how much chaos am I willing to accept" dial. 💀

Special Notes

  • the default error limit is 1.
  • all errors have a time stamp associated with them, which are useful for characterizing intermittent error conditions.
  • the error limit is adjusted for read, write, or data compare failures. this limit is not enforced when flushing data, or for certain AIO wait operations which are considered non-fatal (perhaps this will change).
  • a future release may support an "onerr=" option to control the action of errors (e.g., loop, ignore (continue), or exit).

Syntax:

  • errors=value — the number of errors to tolerate. bestie, that's literally it. 💅

File Limit files= Option 🎀

This option controls the number of tape files to process with tape devices. tape girlies rise up 📼

Special Notes

  • During the write pass, a tape file mark is written after each file. After all files are written, 1 or 2 file marks will be written automatically by the tape driver when the device is closed. the driver's got your back 🫶
  • During reads, each file is expected to be terminated by a file mark and read() system calls are expected to return a value of denoting the end of file. When reading past all tapes files, an errno of ENOSPC is expected to flag the end of media condition. ENOSPC said "no more media, bestie" 😭
  • Writing tape file marks is currently not supported on the QNX Operating System. The release I currently have does not support the mtio commands, and unfortunately the POSIX standard does define this interface (the mtio interface appears to be a UNIX specific standard). Multiple tape files can still be read on QNX systems however. QNX said "not today" 💀

Syntax

files=value

Set number of tape files to process.

Terminal Flow Control flow= Option 🌸

This option specifies the terminal flow control to use during testing. flow check! vibe check! ✨

Special Notes

  • The default flow control is "xon_xoff". default queen 👑
  • When using XON/XOFF flow control, you must make sure these byte codes (Ctrl/Q = XON = ' 21', Ctrl/S = XOFF = ' 23), since the program does not filter these out automatically. Also be aware of terminal servers (e.g., LAT), or modems (e.g., DF296) which may eat these characters. they're hungry, protect your bytes 🍓
  • Some serial lines do support clear-to-send (CTS) or request-to-send (RTS) modem signals. For example on Alpha Flamingo machines, only one port (/dev/tty00) supports full modem control, while the alternate console port (/dev/tty01) does not. Therefore, if running loopback between both ports, you can not use flow control, the test will hang waiting for these signals to transition (at least, I think this is the case). flamingo lore 🦩

Syntax

flow=type

Set flow to: none, cts_rts, or xon_xoff.

History history= Option 🦋

This option sets the number of I/O history entries to record. During failures, the history is dumped, which can be helpful when troubleshooting failures. receipts! keep the receipts! 🧾

Syntax

history=value

Set the number of history request entries.

History Data Size hdsize= Option 💖

When I/O history is enabled, this option controls how many data bytes are saved for each I/O. how much tea to spill ☕

Syntax

hdsize=value

Set the history data size (bytes to save). Default hdsize=32 (set to 0 to disable copy)

Record Increment incr= Option 🔥

This option controls the bytes incremented when testing variable length records. After each record, this increment value (default 1), is added to the last record size (starting at "min=", up to the maximum record size "max="). math but make it fashion 💅

Special Notes

  • If variable length record testing is enabled on fixed block disks and this option is omitted, then "incr=" defaults to 512 bytes. 512, iconic ✨

Syntax

incr=value

Set number of record bytes to increment.

or

incr=variable

Enables variable I/O request sizes.

I/O Direction iodir= Option 🌈

This option allows you to control the I/O direction with random access devices. The default direction is forward. forward, always forward ⭐

Syntax

iodir=direction

Set I/O direction to: {forward or reverse}.

I/O Mode iomode= Option 👑

This option controls the I/O mode used, either copy, test, or verify modes. The copy option was added to do a byte for byte copy between devices, while skipping bad blocks and keeping file offsets on both disks in sync. I've used this option to (mostly) recover my system disk which developed bad blocks which could not be re-assigned. A verify operation automatically occurs after the copy, which is real handy for unreliable diskettes. disk recovery era 💾

Syntax

iomode=mode

Set I/O mode to: {copy, test, or verify}.

IOT Pass iotpass= Option 🎀

This option is used to specify the IOT pass number. When multiple passes occur, dt factors in the pass count to generate unique data during each pass. For example, the IOT seed is normally 0x01010101, and will be multiplied by the pass specified, useful for re-reading previously written IOT data patterns. pass the vibe check 🔁

Syntax

iotpass=value

Set the IOT pattern for specified pass.

IOT Seed iotseed= Option 🌸

This option is used to specify the last IOT pattern seed dt used. When multiple passes occur, dt now factors in the pass count to generate unique data during each pass. For example, the IOT seed is normally 0x01010101, but this is now multiplied by the pass count for uniqueness. seed supremacy 🌱

Syntax

iotseed=value

Set the IOT pattern block seed value.

I/O Type iotype= Option 🦋

This option controls the type of I/O performed, either random or sequential. The default is to do sequential I/O. sequential is the default, but random is fun too 🎲

Special Notes

  • The random number generator used is chosen by defines: RAND48 to select srand48()/lrand48(), RANDOM to select srandom()/random(), and if neither are defined, srand()/rand() gets used by default. Refer to your system literature or manual pages to determine which functions are supported. choose your fighter ⚔️

Syntax

iotype=type

Set I/O type to: {random or sequential}.

The seeks are limited to the data limited specified or calculated from other options on the dt command line. If data limits are not specified, seeks are limited to the size of existing files, or to the entire media for disk devices (calculated automatically by dt). If the data limits exceed the capacity of the media/partition/file under test, a premature end-of-file will be encountered on reads or writes, but this is treated as a warning (expected), and not as an error. warning, not error, bestie ⚠️

Minimum Record Size min= Option 💖

This option controls the minimum record size to start at when testing variable length records. smallest size, biggest heart 🥺

Special Notes

  • By default, tests using fixed length records of block size "bs=" bytes. bs= is the blueprint 📏
  • This option, in conjuntion with the "max=" and "incr=" control variable length record sizes. the trio 👯
  • If variable length record testing is enabled on fixed block disks and this option is omitted, then "min=" defaults to 512 bytes. 512 again, she's everywhere ✨

Syntax

min=value

Set the minumum record size to transfer.

Maxmimum Record Size max= Option 🔥

The option controls the maximum record size during variable length record testing. max out your records 💅

Special Notes

  • If the "min=" option is specified, and this option is omitted, then the maximum record size is set to the block size "bs=". bs= to the rescue 🦸
  • This option, in conjuntion with the "min=" and "incr=" control variable length record sizes. the trio again 👑

Syntax

max=value

Set the maximum record size to transfer.

Logical Block Address lba= Option 🌈

This option sets the starting logical block address used with the "lbdata" option. When specified, the logical block data "enable=lbdata" option is automatically enabled. auto-magic ✨

Syntax

lba=value

Set starting block used w/lbdata option.

Special Notes

  • Please do not confuse this option with the disks' real logical block address. See 's "seek=" or "position=" options to set the starting file position. don't confuse them, bestie 🙈
  • Also note that doesn't know about disk partitions, so any position specified is relative to the start of the partition used. partition relative, periodt 💅

Logical Block Size lbs= Option 🎀

This option sets the starting logical block size used with the lbdata option. When specified, the logical block data (enable=lbdata) option is automatically enabled. lbdata's bestie 🫶

Syntax

lbs=value

Set logical block size for lbdata option.

Data Limit limit= Option 👑

This option specifies the number of data bytes to transfer during each write and/or read pass for the test. set the limit, live your life 💅

Special Notes

  • You must specify either a data limit, record limit, or files limit to initiate a test, unless the device type is "disk", in which case dt will automatically determine the disk capacity. disk does it itself 🦋
  • When specifying a runtime via the "runtime=" option, the data limit controls how many bytes to process for each pass (write and/or read pass). runtime + limit = teamwork 🤝
  • If you specify a infinite "limit=inf" value, each pass will continue until the end of media or file is reached. infinite, no cap ♾️
  • When the "step=value" option is used, limit controls the maximum offset stepped to. step by step 👣

Syntax

limit=value

The number of bytes to transfer.

Munsa (DLM) munsa= Option 🌸

This option is used on Tru64 Cluster systems to specify various distributed lock manager (DLM) options with devices or files. Tru64 cluster represent 🏢

Syntax

munsa=string

Set munsa to: cr, cw, pr, pw, ex.

MUNSA Lock Options:

  • cr — Concurrent Read (permits read access, cr/pr/cw by others) read with friends 📖
  • pr — Protected Read (permits cr/pr read access to all, no write) read only, no writing 🚫
  • cw — Concurrent Write (permits write and cr access to resource by all) write party 🎉
  • pw — Protected Write (permits write access, cr by others) write but protected 🛡️
  • ex — Exclusive Mode (permits read/write access, no access to others) main character energy 👑

For more details, please refer to the dlm(4) reference page. go read dlm(4) 📚

Special Notes

  • MUNSA is an obsolete Tru64 Cluster term which meant MUltiple Node Simultaneous Access. The new term is DAIO for Direct Access I/O. Finally, the last term used is DRD for Distributed Request Dispatcher. terminology glow-up ✨

Common Open Flags flags= Option 🦋

Output Open Flags oflags= Option 🦋

These options are used to specify various POSIX compliant open flags, and system specific flags, to test the affect of these open modes. open flags, open vibes 🚪

Special Notes

  • Each operating system has different flags, which can be queried by reviewing the help text (dt help). dt help is your bestie 🫶

Syntax

flags=flags

Set open flags: {excl,sync,...}.

oflags=flags

Set output flags: {append,trunc,...}.

On Child Error oncerr= Option 🔥

This option allows you to control the action taken by dt when a child process exits with an error. By default, the action is continue, which allows all child processes to run to completion. If the child error action is set to abort, then dt aborts all child processes if any child process exits with an error status. abort or continue, choose your fighter ⚔️

Syntax:

oncerr={abort|continue}
       Set child error action.

Okay bestie, back into the options buffet we go. 🍓

⏰ No Progress Time noprogt= Option

So this one lets you hand dt a time, in seconds, and dt will report when I/O is just... not making progress. Like when your disk is giving nothing. 💀

You use it together with the alarm= option, which is what makes dt periodically check in and report when I/O is taking way too long. This is especially useful during controller failover type testing — like, that's literally the moment you want to know something's stalling. 👑

Syntax:

noprogt=value
       Set the no progress time (in seconds).

🚨 No Progress Time Trigger noprogtt= Option

Same energy, different job: this one takes a time in seconds and it's the moment to kick off the no-progress time trigger script. 🎬

Note: this option does nothing on its own. It has no effect unless the noprogt= option is enabled. Periodt.

Syntax:

noprogtt=value
       Set the no progress time trigger (in seconds).

🙈 No Time notime= Option

This lets you turn off the timing of certain operations (system calls) whenever the no-progress option is switched on. The valid optype values are:

open close read write ioctl fsync msync aiowait

Special Notes ✨

  • This option has no effect, unless the option is enabled.

Syntax:

notime=optype
       Disable timing of specified operation type.

🎀 Terminal Parity Setting parity= Option

This one sets the terminal parity setting dt should use while testing. Cute, simple.

Syntax:

parity=string
       Set parity to: even, odd, or none.

parity=string
       (QNX) Set parity to: even, odd, mark, space, or none.

🔁 Pass Limit passes= Option

This controls how many passes each test does. Slay. 🔥

Special Notes 💅

  • The default is to perform 1 pass.
  • When you're using the of= option, each write/read combination counts as a single pass.
  • When multiple passes are specified, a different data pattern is used for each pass — unless you specified a data pattern or a pattern file.
⚠️ Please keep this in mind when using the dispose=keep option, because using that same file for a subsequent read verify pass will report comparison errors... I've burnt myself this way. :-( 💀

Syntax:

passes=value
       The number of passes to perform.

🌈 Data Pattern pattern= Option

This specifies a 32 bit hexadecimal data pattern for the data. dt comes with 12 built-in patterns and it alternates through them when you run multiple passes. The default data patterns are:

0x39c39c39, 0x00ff00ff, 0x0f0f0f0f, 0xc6dec6de, 0x6db6db6d, 0x00000000,
0xffffffff, 0xaaaaaaaa, 0x33333333, 0x26673333, 0x66673326, 0x71c7c71c

You can also use the special keyword incr= to get an incrementing data pattern, or you can straight up specify a character string (normally wrapped in single or double quotes). iykyk. 🫶

Syntax:

pattern=value
       The 32 bit hex data pattern to use.

or

pattern=iot
       Use DJ's IOT test pattern.

or

pattern=incr
       Use an incrementing data pattern.

or

pattern=string
       The string to use for the data pattern.

📍 File Position position= Option

This gives dt a byte offset to seek to before starting each pass of each test. Get in position bestie. 💅

Syntax:

position=offset
       Position to offset before testing.

🏷️ Prefix prefix= Option

This one lets you define a free format prefix string that gets written at the beginning of every block. It's there to generate uniqueness, which is super useful when data corruption happens. 😭

Certain format control strings get interpreted, and they're listed below.

Syntax:

prefix=string
       The data pattern prefix string.

The prefix format controls permitted are:

Prefix Format Control:

  • %d — The device name.
  • %D — The real device name.
  • %h — The host name.
  • %H — The full host name.
  • %p — The process ID.
  • %P — The parent PID.
  • %u — The user name.

Example:

prefix="%u@%h (pid %p)"

👯 Multiple Processes procs= Option

This specifies how many processes to spawn that all run the same test. It's the easy way to fire off multiple I/O requests at one device or file system. Iconic for stressing stuff out.

Special Notes 🔥

  • The per process limit on Tru64 UNIX is 64, and you can query it with the sysconfig -q proc command.
  • Spawning many processes can render your system useless — well, at least very slow — and it eats up large amounts of swap space (make sure you have plenty!).
  • The parent process simply monitors (waits for) all child processes.
  • When writing to a file system, the process ID (PID) is appended to the file name you gave with the of= option, so you get unique file names. If no pattern is specified, each process is started with a unique data pattern. Subsequent passes cycle through the 12 internal data patterns. Use disable=unique to avoid this behaviour.
  • The spawn() facility, used to execute on a different node, is not implemented on the QNX Operating System at this time.

Syntax:

procs=value
       The number of processes to create.

📚 Set Queue Depth qdepth= Option

Right now this is only implemented on HP-UX. It lets you set the queue depth of the device under test, overriding its default.

Note: the setting is sticky (retained). It remembers. 🫶

Syntax:

qdepth=value
       Set the queue depth to specified value.

🎯 Random I/O Offset Alignment wralign= Option

When you're doing random I/O, this aligns each random block offset to a particular alignment — like 32K, for example.

Syntax:

ralign=value
       The random I/O offset alignment.

📏 Random I/O Data Limit rlimit= Option

This one pairs with random I/O: it specifies the number of bytes to limit random I/O between (starting from block, to this range). It's independent of the data limit option, so don't mix them up bestie. 💅

Syntax:

rlimit=value
       The random I/O data byte limit.

🎲 Random Seed Value rseed= Option

This sets the seed used to initialize the random number generator when you're doing random I/O. When you pick random I/O, the total statistics displays the random seed used during that test — so you can use this option to repeat the random I/O sequence of a test. Lowkey the most underrated option here. ✨

Syntax:

rseed=value
       The random seed to initialize with.

🗂️ Record Limit records= Option

This controls how many records to process for each write and/or read pass of each test. Oh and count= is an alias for this option (supported for dd compatibility). 👑

Special Notes 💖

  • You must specify either a data limit, record limit, or files limit to initiate a test — unless the device type is disk, in which case dt will automatically determine the disk capacity.
  • When you specify a runtime via the runtime= option, the record limit controls how many records process for each pass (write and/or read pass).
  • If you specify an infinite records=Inf value, each pass will continue until the end of media or file is reached.

Syntax:

records=value
       The number of records to process.

⏱️ Run Time runtime= Option

This controls how long the whole test should run. When you use it with a data limit or record limit, multiple passes will be performed until the runtime limit expires. There's a later section called "Time Input Parameters" that describes the shorthand notation for time values. Go read it, it's giving helpful. 💜

Syntax:

runtime=time
       The number of seconds to execute.

🔄 Retry Delay retry_delay= Option

This controls the number of seconds to delay between reads performed after a data corruption. (see the enable=retryDC option) 😭

Syntax:

retry_delay=value
       Delay before retrying operation. (Def: 5)

🍰 Slice slice= Option

This is for random access devices. It works together with the slices=value option — that one divides the media into slices (see below), and then slice=value says which slice to actually test. Since dt does all the math, this makes simultaneous testing from multiple hosts to shared storage way simpler (usually a multi-initiator test requirement). 🫶

Syntax:

slice=value
       The specific disk slice to test.

🎂 Slices slices= Option

Also for random access devices. This divides the media into slices, where each slice contains a different range of blocks to operate on in a separate process. If no pattern is specified, each slice is started with a unique data pattern, and subsequent passes alternate through dt's 12 internal patterns. ✨

Syntax:

slices=value
       The number of disk slices to test.
Note: this option can be used in conjunction with multiple processes and/or asynchronous I/O options to generate a heavy I/O load — great for stress testing! 🔥

⏭️ Record Skip skip= Option

This specifies the number of records to skip before starting each write and/or read pass of each test. The skips are accomplished by reading records. (So it's not free, bestie.) 🙈

Syntax:

skip=value
       The number of records to skip past.

🔍 Record Seek seek= Option

This specifies the number of records to seek past before starting each write and/or read test. The seeks are accomplished by lseek()'ing past records, which is much faster than skipping when you're on random access devices. Slay. 💅

Syntax:

seek=value
       The number of records to seek past.

🪜 Data Step step= Option

This gives you non-sequential I/O requests on random access devices. Normally dt does sequential reads & writes, but this option says: seek past step bytes after each request. Chaos, but the controlled kind. 🦋

Special Notes ⭐

  • The limit=value option can be used to set the maximum offset.

Syntax:

step=value
       The number of bytes seeked after I/O.

🐌 Terminal Speed speed= Option

This specifies the terminal speed (baud rate) to set up before the test starts. dt supports all valid baud rates, but ngl — some speeds may not be supported by all serial line drivers, and in some cases specifying higher speeds may result in hardware errors (e.g., silo overflow, framing error, and/or hardware/software overrun errors). 😭

The valid speeds accepted by dt are:

0 50 75 110 134 150

200 300 600 1200 1800 2400
4800 9600 19200 38400 57600 115200

okay so zero baud is accepted, bestie, but it's basically only there for testing purposes (some systems use zero to hang up modems, iykyk). And the higher baud rates? Those only work on systems that actually define the Bxxxxx speeds in termios.h. so like, don't come for me if your OS says no. 💅

Special Notes

  • The default speed is 9600 baud. that's the vibe, that's the baseline, periodt.

Syntax:

speed=value
       The tty speed (baud rate) to use.

Terminal Read Timeout timeout= Option

This one sets the timeout, in 10ths of a second, for when you're testing terminal line interfaces. it's the timeout between each character after the first character shows up — which is literally the thing that stops your tests from just hanging forever when a character gets garbled and lost. iconic protective behavior honestly. 🫶

Special Notes

  • The default terminal timeout is 3 seconds.
  • The default timeout gets automatically adjusted for slow baud rates. it just knows.

Syntax:

timeout=value
       The tty read timeout in .10 seconds.

Terminal Read Minimum ttymin= Option

This option sets the minimum number of characters to read — which is a fancy way of saying it sets the VMIN tty attribute. yes bestie, we're in the tty guts now. 🌸

Special Notes

  • The tty VMIN field normally gets sets to the value of the block size ().
  • ngl, on some systems the VMIN field is an unsigned char, so the max value is 255. rude but true.
  • On QNX though? That field is an unsigned short, so a maximum of 65535 is valid. QNX said "we do a little more". 💅

Syntax:

ttymin=value
       The tty read minimum count (sets vmin).

Trigger Action trigger= Option

This specifies a trigger action to take whenever an error occurs and/or when the no-progress time has been exceeded (peep "enable=noprog" for that one). Its main purpose is triggering an anlyzer and/or stopping I/O by some means (panic, etc) when you're trouble-shooting. it's giving "something went wrong, do the dramatic thing". 😭

Syntax:

trigger=type The trigger to execute during errors.

Trigger Types:

  • br — Execute a bus reset.
  • bdr — Execute a bus device reset.
  • seek — Issue a seek to the failing lba.
  • cmd:string — Execute command with these args: string dname op dsize offset position lba errno

The first three options require Scu in your PATH.

When you specify the "cmd:" type — which invokes a program/script — these arguments get passed on the command line:

Format: cmd dname op dsize offset position lba errno noprogtime

Where:

  • dname = The device/file name.
  • op = open/close/read/write/miscompare/noprog
  • dsize = The device block size.
  • offset = The current file offset.
  • position = The failing offset within block.
  • lba = The logical block address (relative for FS).
  • errno = The error number on syscall errors.
  • noprogtime = The no-progress time (in seconds).

Multiple Volumes volumes= Option

Multi-Volume Records vrecords= Option

These two are for removal media devices — they define how many volumes and how many records on the last volume to process (think tapes, etc). Using these means you do not have to guess at a data limit or record limit just to overflow onto the next volumes. and the glow-up? they automatically set the "enable=multi" option for you. no cap. ✨

Syntax:

volumes=value
       The number of volumes to process.

vrecords=value
       The record limit for the last volume.

Enable enable= and Disable disable= Options

These are how you turn program flags on or off — flags that either alter default test modes, alter test actions, or hand you extra debugging info. You can pass one single flag, or a whole comma-separated lineup (e.g., "enable=aio,debug,dump"). yes bestie, stack them. 🎀

Syntax:

enable=flag Enable one or more of the flags below.

disable=flag Disable one or more of the flags below.

The flags which can be enabled or disabled are described below.

POSIX Asynchronous I/O aio Flag

This flag controls whether you use POSIX Asynchronous I/O during testing, instead of the synchronous I/O read() and write() system calls. async girlies rise. 🔥

Special Notes

  • Beware, you may need to rebuild on new versions of Tru64 Unix due to POSIX changes and/or AIO library changes between major releases. consider yourself warned, bestie.
  • Reference the "aios=" option for more special notes.

Flag:

  • aio — POSIX Asynchronous I/O. (Default: disabled)

Reporting Close Errors cerror Flag

This flag controls whether close errors get reported as an error or a failure. When it's disabled, close errors get reported as a warning instead. This flag is meant as a workaround for device drivers that improperly return failures when closing the device — yes, those exist, and yes, it's annoying. 😭 Many system utilities ignore close failures, but when you're testing terminals and tapes, the close status us very important. For example with tapes, the close reflects the status of writing filemarks (which also flush buffered data), and the rewind status. so like, don't skip it.

Flag:

  • cerrors — Report close errors. (Default: enabled)

Data Comparison compare Flag

This flag disables data verification during the read pass of tests. You'd want to disable it to read to end of file/media to obtain maximum capacity statistics, or to obtain maximum performance statistics (less overhead). speedrun mode, basically. 🦋

Flag:

  • compare — Data comparison. (Default: enabled)

Core Dump on Errors coredump Flag

This controls whether a core file is generated, via abort(), when dt is exiting with a failure status code. It's mainly for program debug and honestly not of much interest to normal users. When testing multiple processes via fork(), it's useful if your OS debugger doesn't support debugging child processes. niche but valid. 💜

Flag:

  • coredump — Core dump on errors. (Default: disabled)

Diagnostic Logging diag Flag

This one is only valid on Tru64 Unix. When enabled, error messages get logged to the binary error logger — which is super useful for correlating device error entries with test failures. heads up though: the logging only occurs when running as superuser (API restriction, not mine!). 🙈

Flag:

  • diag — Log diagnostic msgs. (Default: disabled)

Debug Output debug Flag

Verbose Debug Output Debug Flag

Random I/O Debug Output rdebug Flag

These flags enable two different levels of debug, which is genuinely useful when you're trouble-shooting certain problems (i.e., what is dt doing to cause this failure??). Both flags can be specified together for full debug output. go big. 💅

Flag:

  • debug — Debug output. (Default: disabled)
  • Debug — Verbose debug output. (Default: disabled)
  • edebug — End of file debug. (Default: disabled)
  • rdebug — Random debug output. (Default: disabled)
  • tdebug — Timer debug output. (Default: disabled)

Dump Data Buffer dump Flag

This flag controls dumping of the data buffer during data comparision failures. If a pattern file is being used, then the pattern buffer is also dumped for easy comparision purposes — side by side, adorable. To prevent too many bytes from being dumped, esp. when using large block sizes, dumping is limited to 512 bytes of data (was 64, recently increased). glow-up fr fr. ✨

Special Notes

  • When the failure occurs within the first 64 bytes of the buffer, dumping starts at the beginning of the buffer.
  • When the failure occurs at some offset within the data buffer, then dumping starts at (data limit/2) bytes prior to the failing byte to provide context. it's giving backstory. 🌸
  • The start of the failing data is marked by an asterisk '*'.
  • You can use the option to override the default dump limit.
  • Buffer addresses are displayed for detection of memory boundary problems.

Flag:

  • dump — Dump data buffer. (Default: enabled)

Tape EEI Reporting eei Flag

This option controls the reporting of Extended Error Information (EEI) on Tru64 UNIX systems, for tape devices when errors occur. The standard tape information available from mt is reported, along with the EEI status, CAM status, and SCSI request sense data. This is excellent information to help diagnose tape failures. (thank-you John Meneghini!) 👑

Flag:

  • eei — Tape EEI reporting. (Default: enabled)

Flush Terminal I/O Queues flush Flag

This flag controls whether the terminal I/O queues get flushed before each test begins. And bestie, this must be done — otherwise residual characters get left in the queues from a prior test, and then you get data verification errors. Residual characters may also be left from a previous XOFF'ed terminal state (output was suspended). clean slate or chaos, your choice. 🧚

Flag:

  • flush — Flush tty I/O queues. (Default: enabled)

History Dumping hdump Flag

This controls dumping the history entries at the end of a test. Normally dt only dumps the history during errors, but when this option is enabled, it dumps the history when exiting. Useful if you're timing I/O's, or you just wanna see the LBA's I/O went to, etc. nosy in the best way. 🍓

Flag:

  • hdump — History dump. (Default: disabled)

History Timing htiming Flag

This flag controls the timing of history entries. Please be aware: enabling timing of each I/O will impact your overall test performance, because an extra system call is used to obtain system time. tradeoffs, bestie, tradeoffs. 😭

Flag:

  • htiming — History timing. (Default: disabled)

Log File Header header Flag

When a log file is specified, dt automatically writes the command line and dt version information at the beginning of the log file. This option lets you control whether that header gets written. receipts at the top, or not. 💅

Flag:

  • header — Log file header. (Default: enabled)

Loop On Error looponerror Flag

This flag controls lopping on data corruption rereads. Which can be helpful in capturing the failing read request on an analyzer. catch it in the act. 🔥

Special Notes

  • Also see "retry_delay=value" and retryDC flag control.

Flag:

  • looponerror — Loop on error. (Default: disabled)

Logical Block Data Mode lbdata Flag

This option enables a feature called logical block data mode. Basically it allows reading/writing of a 4-byte (32-bit) logical block address at the beginning of each data block tested. The block number is stored using SCSI byte ordering (big-endian), which matches what the SCSI Write Same w/lbdata option uses — so dt can verify this pattern, generated by scu's "write same" command. obsessed with the consistency honestly. ✨

Special Notes

  • The starting logical block address defaults to 0, unless overridden with the "lba=" option.
  • The logical block size defaults to 512 bytes, unless overridden with the "lbs=" option.
  • The logical block address is always inserted started at the beginning of each data block.
  • Enabling this feature will degrade performance statistics (slightly). tiny price, big payoff. 🫶

Enable Loopback Mode — the loopback flag 🔁

okay so this flag says: use either the input or the output file in loopback mode, bestie. In loopback mode, dt fork()s, and the child process becomes the reader while the parent process becomes the writer. In previous versions of dt, you had to specify the same input and output file to get loopback mode going. When you pass this flag, dt automatically duplicates the input or output device for you — which is a little cleaner than the old method (and yeah, the old method still works, no cap).

Some people may argue that dt should automatically enable loopback mode the moment it detects a single terminal or FIFO device. The rationale behind not doing this is described below:

  • You may wish to have another process as reader and/or writer (which also includes another program — not necessarily this one).
  • You may wish to perform device loopback between two systems (e.g., to verify the terminal drivers of two operating systems are compatible).
  • A goal of dt is to force (hardcode) actions or options to make the program more flexible. A minimum of validity checking is done to avoid being too restrictive, although hooks exists to do this.

Special Notes ✨

  • The read verify flag is automatically disabled.
  • This mode is most useful with terminal devices and/or FIFO's (named pipes).

Microsecond Delays — the microdelay flag ⏱️

This flag tells dt that delay values, i.e. "sdelay=" and others, should be executed using microsecond intervals, rather than second intervals. (thank-you George Bittner for implementing this support! 🫶)

Flag:

  • microdelay — Microsecond delays. (Default: disabled)

Memory Mapped I/O — the mmap flag 🗺️

This flag controls whether the memory mapped API is used for testing. This test mode is currently supported on SUN/OS, Tru64 UNIX, and Linux operating systems.

Special Notes 💅

  • The block size specified "bs=" be a multiple of the system dependent page size (normally 4k or 8k).
  • An msync() is done after writing and prior to closing to force modified pages to permanent storage. It may be useful to add an option to inhibit this action at some point, but my testing was specifically to time mmap performance. Obviously, invalidating the memory mapped pages kind of defeats the purpose of using memory mapped files in the first place.
  • Specifying multiple passes when doing a read verify test gives you a good indication of the system paging utilization on successive passes.
  • Memory mapping large data files (many megabytes) may exhaust certain system resources. On an early version of SUN/OS V4.0?, I could hang my system by gobbling up all of physical memory and forcing paging (this was certainly a bug which has probably been corrected since then).

Flag:

  • mmap — Memory mapped I/O. (Default: disabled)

Test Modem Lines — the modem flag ☎️

This flag controls the testing of terminal modem lines. Normally, dt disables modem control, via setting CLOCAL, to prevent tests from hanging. When this flag is enabled, dt enables modem control, via clearing CLOCAL, and then monitoring the modem signals looking for either carrier detect (CD) or dataset ready (DSR) before allowing the test to start.

Special Notes 🎀

  • The program does not contain modem signal monitoring functions for all operating systems. The functions in are specific to Tru64 UNIX and ULTRIX systems, but these can be used as templates for other operating systems.

Flag:

  • modem — Test modem tty lines. (Default: disabled)

Multiple Volumes — the multi flag 📼

This flag controls whether multiple volumes are used during testing. When this flag is enabled, if the data limit or record count specified does not fit on the currently loaded media, the user is prompted to insert the next media to continue testing. Although this is used mostly with tape devices, it can be used with any removeable media.

Flag:

  • multi — Multiple volumes. (Default: disabled)

No I/O Progress — the noprog flag 😴

This flag controls whether dt will check for slow or no I/O progress during testing.

Special Notes — enabling this flag will do nothing by itself. The "alarm=" option specifies the frequency of how often dt checks for no progress.

  • The "noprogt=secs" option specified the no I/O progress time.
  • If "noprogt=" is omitted, it defaults to the "alarm" time value.
  • The noprog flag is implicitly enabled by the "noprogt=value" option.

Flag:

  • noprog — No progress check. (Default: disabled)

Prefill — the prefill flag 🧺

This flag controls the buffer prefill normally performed prior to reads. Normally, dt prefills the buffer with the inverted data pattern (1st four bytes). This, of course, ensures the data is overwritten with data read, but also imposes overhead not always desirable.

Special Notes 🌸

  • When IOT pattern is used, this flag is automatically enabled, since IOT blocks are unique.

Flag:

  • prefill — Prefill read buffer. (Default: enabled)

Control Per Pass Statistics — the pstats flag 📊

This flag controls whether the per pass statistics are displayed. If this flag is disabled, a single summary line is still displayed per pass and the total statistics are still displayed in the full format.

Flag:

  • pstats — Per pass statistics. (Default: enabled)

Read After Write — the raw flag ✍️➡️📖

This flag controls whether a read-after-write will be performed. Sorry, raw does not mean character device interface, bestie. Normally dt performs a write pass, followed by a read pass. When this flag is enabled, the read/verify is done immediately after the write.

Flag:

  • raw — Read after write. (Default: disabled)

Tape Reset Handling — the resets flag 🎞️

This option is used during SCSI bus and device reset testing, to reposition the tape position (tapes rewind on resets), and to continue testing. This option is only enabled for Tru64 UNIX systems (currently), since this option requires reset detection from EEI status, and tape position information from the CAM tape driver (although dt also maintains the tape position as a sanity check against the drivers' data).

Flag:

  • resets — Tape reset handling. (Default: disabled)

Retry Data Corruptions — the retryDC flag 🔄

This flag controls whether a data corruption retry is performed. A second read is done to re-read the data, with direct I/O for file systems, and the data is compared against the previous read data, and the expected data. If the reread data matches the expected data, then dt assumes a "read failure" occurred, otherwise if the reread data matches the previous read, dt assumes a "write failure" (the data was written incorrectly).

Flag:

  • retryDC — Retry data corruptions. (Default: enabled)

Control Program Statistics — the stats flag 📈

This flag controls whether any statistics get displayed (both pass and total statistics). Disabling this flag also disabled the pass statistics described above.

Flag:

  • stats — Display statistics. (Default: enabled)

Table(sysinfo) timing — the table flag 🗂️

On Tru64 UNIX systems, this option enables additional timing information which gets reported as part of the statistics display. (thanks to Jeff Detjen for adding this support! 🫶)

Flag:

  • table — Table(sysinfo) timing. (Default: disabled)

System Log — the syslog flag 📝

This flag controls logging startup/finish and errors being logged to the system logger. This can be helpful when correlating dt's errors with system (driver/file system) error messages.

Flag:

  • syslog — Log errors to syslog. (Default: disabled)

Timestamp Blocks — the timestamp flag 🕰️

This flag controls whether blocks are timestamped when written. The timestamp is skipped during data comparisions, but is displayed if any remaining data is incorrect.

Special Notes ⭐

  • When IOT or lbdata patterns are used, the block number is overwritten by the timestamp.
  • This flag is a stop-gap, until block tagging (w/more information) is implemented.

Flag:

  • timestamp — Timestamp each block. (Default: disabled)

Unique Pattern — the unqiue flag 👑

This flag controls whether multiple process get a unqiue data pattern. This affects processes started with the "slices=" or the "procs=" options. This only affects the procs= option when writing to a regular file.

Flag:

  • unique — Unique pattern. (Default: enabled)

Verbose Output — the verbose flag 🗣️

This flag controls certain informational program messages such as reading and writing partial records. If you find these messages undesirable, then they can be turned off by disabling this flag.

But beware, partial reads or writes of disk records if not at EOF is usually a problem! 😭

Flag:

  • verbose — Verbose output. (Default: enabled)

Verify Data — the verify flag ✅

This flag controls whether the read verify pass is performed automatically after the write pass. Ordinarily, when specifying an output device via the "of=" option, a read verify pass is done to read and perform a data comparision. If you only wish to write the data, and omit the data verification read pass, then disable this flag.

Flag:

  • verify — Verify data written. (Default: enabled)

Special Notes 🦋

  • If you don't plan to ever read the data being written, perhaps for performance reasons, specifying "disable=compare" prevents the data buffer from being initialized with a data pattern.
  • This verify option has no affect when reading a device. You must disable data comparsions via "disable=compare".

Program Delays ⏳

dt allows you to specify various delays to use at certain points of the test. These delays are useful to slow down I/O requests or to prevent race conditions when testing terminals devices with multiple processes, or are useful for low level driver debugging. All delay values are in seconds, unless you specify "enable=microdelay", to enable micro-second delays.

Close File — cdelay= Delay 🚪

This delay, when enabled, is performed prior to closing a file descriptor.

Delay:

  • cdelay=value — Delay before closing the file. (Def: 0)

End of Test — edelay= Delay 🏁

This delay, when enabled, is used to delay after closing a device, but prior to re-opening the device between multiple passes.

Delay:

  • edelay=value — Delay between multiple passes. (Def: 0)

Read Record — rdelay= Delay 📖

This delay, when enabled, is used prior to issuing each read request (both synchronous read()'s and asynchronous aio_read()'s).

Delay:

  • rdelay= value — how long to chill before reading each record. (Default: 0)

Start Test — sdelay= Delay

okay so bestie, this delay, when it's enabled, gets used before the test even kicks off. And here's the tea 🫖: when you're testing terminal devices, and you're not in self loopback mode, the writing process (that's the parent) automatically delays 1 second, so the reading process (the child) has time to start up and set up its' terminal characteristics. If that delay didn't happen before the first write, the reader might not have its' terminal characteristics (flow, parity, & speed) set up yet, and it could inadvertently flush the writer's data or receive garbled data. 😭

Delay:

  • sdelay= value — delay before starting the test. (Default: 0)

Child Terminate — tdelay= Delay

This one is used by child processes before they exit, so the parent process gets enough time to clean up and wait for the child. Why tho? Because if the child exits first, a SIGCHLD signal may force the parent into its termination signal handler before it's ready to be there. It's a very simplistic approach to preventing this parent/child race condition, and right now it's only used by the child for terminal loopback testing. 🧚

Delay:

  • tdelay= value — delay before child terminates. (Default: 1)

Write Record — wdelay= Delay

This delay, when enabled, is used before issuing each write request — and yes, that means both synchronous write()'s and asynchronous aio_write()'s. no skips ✨

Delay:

  • wdelay= value — delay before writing each record. (Default: 0)

Numeric Input Parameters

For any options that take numeric input, the string you type can contain any combination of the following characters:

Special Characters:

  • w — words (4 bytes)
  • q — quadwords (8 bytes)
  • b — blocks (512 bytes)
  • k — kilobytes (1024 bytes)
  • m — megabytes (1048576 bytes)
  • p — page size (8192 bytes)
  • g — gigabytes (1073741824 bytes)
  • t — terabytes (1099511627776 bytes)
  • inf or INF — infinity (18446744073709551615 bytes)

Arithmetic Characters:

  • + — addition
  • - — subtraction
  • * or x — multiplication
  • / — division
  • % — remainder

Bitwise Characters:

  • ~ — complement of value
  • >> — shift bits right
  • << — shift bits left
  • & — bitwise 'and' operation
  • | — bitwise 'or' operation
  • ^ — bitwise exclusive 'or'

The default base for numeric input is decimal, but you can override that default by specifying 0x or 0X for hexadecimal conversions, or a leading zero 0 for octal conversions. 🔢

NOTE: certain values will vary depending on the operating system and/or machine you're running on. For example, the page size is system dependent, and the value for Infinity is the largest value that will fit into an unsigned long long (the value shown above is for 64-bit systems), or double for systems which don't support long long.

Time Input Parameters

When you're setting the run time with the runtime= option, the time string you enter can contain any combination of the following characters:

Time Input:

  • d — days (86400 seconds)
  • h — hours (3600 seconds)
  • m — minutes (60 seconds)
  • s — seconds (the default)

Arithmetic characters are permitted, and implicit addition is performed on strings of the form '1d5h10m30s'. 🕐

🔮 Future Enhancements 🔮

Originally, dt was written to be a generic test tool, designed to test any device, and even though that was (mostly) accomplished, device-specific tests needed to be developed — and they were, based on the device type detected or specified by the dtype= option if it wasn't determined automatically.

Some of the features that have been requested include:

  • Support for an initialization file () to setup frequent or common test parameters.
  • Develop corruption analysis logic. What is this? Folks familiar with HP's Hazard know how valuable this is: data re-read logic, I/O history, metadata prowlers, and detailed analysis of expected and received data. A lot of work is involved here, especially with file system prowlers, which are responsible for converting file system data structures to physical underlying LBA's, to help identify bad data in analyzer traces.
  • Improved file system testing. Although not developed as a file system exerciser, many folks use it this way. Multiple processes creating unique data files generates a data load, but many file system specific features, such as truncating files, file locking, creating lots of metadata (via subdirectories), and many more are not tested well. Major effort here!
  • Supporting multiple devices in one invocation (perhaps a comma separated list). Although multiple processes or threads could accomplish this, it does add complexity requiring locking and switching to reentrant library API's, and the savings is shared code is minimal (I think) since most of the address space is data buffers.
  • Multiple threads for I/O is likely to be implemented one day. The reason I haven't rushed this I/O method, is because POSIX AIO provides my need, and most modern day OS's now support POSIX AIO. Interestingly enough, the Linux AIO is implemented via POSIX threads! Threads are interesting to overcome OS's with a process limit, and threads (should) reduce system resources.
  • Incorporate SCSI library to implement bus/target/lun reset triggers, etc.
  • Interactive interface to keep the device open, like does, to allow more creative tests, especially for tapes and tape libraries (although most use for disk testing).
  • Add output formats to allow statistics to be imported to tools such as MS Excel, etc.
  • GUI front-end? Might be nice, but not necessary for test automation. Volunteers?
  • Port to VMS? There's a need, so given the time, this will likely happen.
  • Native Windows? Mostly there, thanks to the HP Hazard India team, but unfortunately I no longer have a Windows development environment, so I cannot supply updates. The code needs a few tweaks for file system testing, ported for raw I/O testing initially.
  • iozone supplies many of the features above, so you may wish to consider this tool too. It's difficult, if not impossible, to supply sufficient features for everyones test needs!

💖 Final Comments 💖

I'm happy to report that it's getting wide spread use all over the world! 🌍 Storage groups, terminal/lat groups, Q/A, developers, and other peripheral qualification groups are using it as part of their testing. I guess maybe this will be my (computer) legacy? 😭

Anyways, I hope you find it as useful as I have. This is usually one of the first tools I port to a new operating system, since it's an excellent diagnostic and performance tool (it gives me a warm and fuzzy feeling 🥰).

👑 AUTHOR 👑

Written by Robin Miller <Robin.T.Miller@gmail.com>

and that's a wrap bestie!! 🎀 you just read dt version 16.20, dated 27 Jul 2009, aka dt(1). go forth and stress-test responsibly, mwah 💅✨

📦 where this page comes from