Command
line options and help
Options
devio has only two command line
options:
- -h [subject]
- Output help on subject subject.
With no argument outputs a short help message. By default
devio is built with full help, however this increases the size of the
devio program considerable. If devio has been compiled
without help only the short help message will be available.
- -v {commands}
- Perform write
verification. Instead of writing devio checks the current
device contents to ensure that they match what would have been
written. If a difference is detected devio exits immediately
with a failure error code.
Help
devio has extensive built in
help, about one third of the executable size is help strings.
The help within the program should be up to date, this manual may not
be. Even though there is a lot of help text it is still
fairly brief; use the built-in help to verify command syntax once you
understand the commands.
To get help on a specific
command use:
devio -h 'cc'
Where cc
are the two characters of the command. The letters
of the command should be quoted (with single quotes) to avoid shell
interpretation of the command.
devio also recognises a number
of keywords which give overview information. These keywords
may be abbreviated where unambiguous.
- devio -h commands
- Lists all the commands and
some basic help information. Commands are grouped into
classes followed by a keyword in square brackets; [keyword].
To get more help give keyword
as an argument to -h.
- devio -h additional
- This explains the syntax of
the 'commands'
help.
- devio -h conditional
- Documentation of conditional
execution, both commands and elements of expressions can be executed
conditionally and within loops.
- devio -h exit
- How to cause an immediate
exit from a devio script.
- devio -h io
- General help for the IO
commands.
- devio -h write
- Information about commands
which write bytes to the output.
- devio -h messages
- Information about commands
which write to standard output.
- devio -h assign
- How to assign to variables
within devio scripts.
- devio -h string
- Output the syntax of a
string command argument.
- devio -h number
- Output the syntax of numbers
(for commands which take numeric arguments) as well as general help for
numeric expressions.
- devio -h operator
- Output help for the
operators available for use in numeric expressions.
Exit codes
The devio program exits with a status (exit) code which indicates
whether a failed write within devio has modified an output file.
This may be important for error recovery and to inform the user of a
script how to recover from the problem. Exit codes are as follows:
- exit code 0
- Success exit - the program script was parsed and executed without
errors, any write operations have been synced to the underlying file
system.
- exit code 1
- Failure exit - an error occured (and an error message will have
been produced), however no write was made to any output device.
- exit code 3
- Failure exit, an error occured after
a successful write to an output device.
If the exit code is non-zero no attempt has been made to flush
output data - in particular even with exit code 3 no fdatasync(2) has been attempted.
Exit from devio can also be
accomplished from the script using the !!
and !? commands. In this
case all writes are completed and the fdatasync(2) call is executed. It is recommended
that error codes 1 and 3 are not used with these commands to avoid
confusion.