To facilitate scripting, NTUtils programs follow certain standards regarding their use of options, stdout, stderr, and return codes.

Usage Standards

Every NTUtils program supports the --help option. For the help option, the NTUtils program will display a standard usage text describing all available options on stderr, and will not do anything else.

Every NTUtils program supports the --xml option, which produces XML output (see below).

Most NTUtils programs also support common options for remote administration.

Process Selection

For NTUtils programs that operate on processes, common options and semantics are shared:

  -i [ --pid ] arg        : Specify process id
  -n [ --name ] arg       : Specify process name
  -s [ --substr ]         :   Process name is a substring match

The processes to act on may be specified by process id (--pid), by name (--name) or by name substring (--substr --name). Either the process id or name may be specified, but not both. Any actions that do anything other than collect and display information require a process id or name, but read-only actions will run against all processes in the system if neither is specified. When processes are specified by name or name substring, the action is taken against all processes matching that name or name substring. The extension of the process (e.g., .exe) may be provided but is not necessary when specifying processes by name.

Process id 0 cannot be specified for any type of action. On NT-based systems, this is the idle process.

Option Parsing

Every option has a short (single character) and long form. An option may have a required or an optional argument (or no argument).

Short options are specified by a preceding hyphen, e.g., -a. Arguments for short options may be separated from the option by whitespace, or they may not, e.g., -p bob and -pbob are equivalent. However, if an option argument starts with a hyphen, it must be specified without whitespace: -p -bob is parsed as two options -p and -b, but -p-bob is parsed as a single option -p with argument -bob.

Short options without arguments may be combined into short option runs, e.g., -ab and -a -b are equivalent as long as option -a does not take an argument. An option that takes a required or optional argument may end the run, e.g., -abp bob, which would be equivalent to -abpbob.

Long options are specified by two preceding hyphens, e.g., --substring. Arguments for long options may be separated from the option by whitespace, or by a single equals sign, e.g., --password bob and --password=bob are equivalent. However, if an option argument starts with a hyphen, it must be specified using the equals sign: --password -bob is parsed as two options, but --password=-bob is parsed as a single option with argument.

Operational Standards

When performing an action against a list of processes (or computers), if one of the actions fails, the program continues with rest of the list. The context of the error is output with the error, so the user should be able to determine to which process (or computer) the error applies.

Output Standards

All results of any operations, be they warnings, errors, or success messages, are output on stdout. Stderr is normally used for interactive reasons (e.g., prompting for a password or displaying the help text). Output may also be sent to stderr if there is an unrecoverable error; this only includes option parsing errors and program bugs.

Return Code Standards

All NTUtils programs return 0 if there was no error, -1 if there was at least one error detected (details in stdout), and 1 if the help option was specified or if there was some unrecoverable error (details in stderr).

XML Output Standards

The root node of the XML output is the name of the NTUtils program, and this node has at least one attribute version. This is the version of the XML output, not the version of the NTUtils program.

XML Output Versions

XML version numbers are a major number and a minor number separated by a period. The minor version number is incremented when there are new nodes or attributes defined. The major version number is incremented when there is a non-backwards-compatible change. As long as the program reading the XML ignores unknown nodes and attributes, it will remain compatible until the major version number is incremented.

XML version numbering is completely independent for each NTUtils program.

XML Common Version 1.0

The root node will have at least one child. Children of the root node may be info nodes, warning nodes, error nodes, context nodes, or result nodes.

Info Nodes

Info nodes do not have any children. They cannot be a child of any node other than the root node. The purpose of info nodes is to describe what the NTUtils program is attempting to do. The root node may have several children that are info nodes.

Info Nodes (Action)

An info node may have a single attribute action, which specifies what action the NTUtils program is attempting to do.

Info Nodes (Process Selection)

An info node may have a single attribute target_process_id, or it may have two attributes target_process_name and exact_match, specifying the processes targeted. Alternatively, it may have a single attribute target_process with the value all, indicating that the action will be performed for all processes.

Warning Nodes

A warning node either has a single attribute message, or it has a single child error node.

Error Nodes

All error nodes have an attribute type, which indicates the source of the error. Common values include Win32, WNet, and General. All error nodes also have an attribute message, which has a human-readable error message. Error nodes may only have other error nodes as children.

Some error nodes have an attribute function, which specifies the function call that caused the error. Win32 and WNet error nodes always have this attribute.

Win32 error nodes also have an attribute code, specifying the actual error code value.

WNet error nodes, depending on the error value, will either have an attribute code, with the same meaning as the Win32 error node attribute; or these nodes may have an attribute provider, specifying which network provider caused the error.

Context Nodes

Context nodes act as containers for error, warning, and result nodes. Context nodes may also contain other context nodes.

Context Nodes (Computer)

Computer context nodes have an attribute computer, specifying the computer name or IP address of the target.

Context Nodes (Process)

Process context nodes have attributes process_name and process_id, identifying the process.

Result Nodes

Result nodes specify the result of an action. Most result nodes have a single attribute value, containing the result of the action. Note that errors are never output as a result node; they are output as an error node.