Help > Command line - what is it for and how to use?

What is the command line needed for?

Zentimo's command line allows to operate devices from the command line console. It is a full-fledged console application letting you perform the most of operations that the GUI version does: to see device list, to stop a device, to return it back, find out what processes are locking a device.

It is useful for using in batch scripts that interact with hot-plug devices. Here are some examples of usage:

Data backup to an external backup HDD and its auto stopping
A script that disables TrueCrypt (drive encryption tool) first and then stops the drive.
Testing a software to work with USB

The command line is implemented as a separated console application 'usr.exe', which is located in the program folder - %Program Files%\Zentimo\

Command line syntax

The common rules of the syntax are:

usr <command_name> [command_parameters]

, where

command_name - one of the listed below command names

command_parameters - parameter set of the command, e.g. for "stop" command it can be either a device name or a drive letter

Supported commands:

stop	Stops a device
forcedstop	Forcibly stops a device
return	Returns a device back
forcedreturn	Forcibly returns a device back
list	Displays the device list
wholocks	Displays the list of processes that prevent a device from being stopped or returned back
help <command_name>	Displays help on <command_name> command
help errs	Displays the list of returned error codes (errorlevels)
help	Displays help on command line

Errorlevels returned by the command line

0 - The operation is successfully completed
1 - The device with the given parameters has not been found
2 - The device cannot be stopped or returned back. This error might happen when the device is locked by another program (in case of "return" command, this code means that the device's neighbour at USB hub might be locked by some processes). Also it may happen if the device is not physically hot-swappable
3 - Incorrect command syntax
4 - The command is unknown
5 - Cannot find processes that are locking: the device (on device stopping) or its neighbours at USB hub (on device returning). It may happen if the device either now is free to eject, or it is locked by a process run with more privileges (e.g. under System account)
6 - A technical error occured while searching for device locking processes
7 - the command is not supported by a specific device

Detailed command descriptions

stop

Intended to device safe removal.

Syntax:

usr stop <command_parameters>

Possible <command_parameters>:

-d DriveLetter	Stops a device by its DriveLetter. You can specify just a drive letter ("C"), a drive letter and ":" ("C:") as well as a path to a folder or a file on the drive
-n DeviceName	Stops a device by its name (part of a name is also acceptable). "Name" - is those name which is displayed by usr list command

Examples:

"usr stop -d g:"	Stops a device that has drive g:
"usr stop -n Sony"	Stops a device with "Sony" word in the name

forcedstop

Forcibly stops the device. If the device cannot be stopped it closes all files and programs preventing this action and try to to stop the device again

Attention! This command closes all opened files from the device if they exist. So use this command if you are sure that there are no important data to save!

Syntax:

usr forcedstop <command_parameters>

Possible <command_parameters>:

-d DriveLetter	Forcibly stops a device by its DriveLetter. You can specify just a drive letter ("C"), a drive letter and ":" ("C:") as well as a path to a folder or a file on the drive
-n DeviceName	Forcibly stops a device by its name (part of a name is also acceptable). "Name" - is those name which is displayed by usr list command

Examples:

"usr forcedstop -d g:"	Stops a device that has drive g:
"usr forcedstop -n Sony"	Stops a device with "Sony" word in the name

return

Intended to return stopped but not yet unplugged device back.

Syntax:

usr return <command_parameters>

Possible <command_parameters>:

-d DriveLetter	Returns a device by its DriveLetter. You can specify just a drive letter ("C"), a drive letter and ":" ("C:") as well as a path to a folder or a file on the drive
-n DeviceName	Returns a device by its name (part of a name is also acceptable). "Name" - is those name which is displayed by usr list command

Examples:

"usr return -d g:"	Returns a device back that has drive g: back
usr return -n "Sony"	Returns a device back with "Sony" word in its name

forcedreturn

Forcibly returns just stopped device back. If the device cannot be returned it closes all files and programs preventing this action and try to return the device again. Works only for USB 1.x/2.0 ports.

Attention! In order to return the device back the command reboots the USB hub wh ere the device is connected to. Therefore this operation will also cause stoppin g and reactivation of all other neighbor devices connected to the same hub, and files opened by some processes from these neighbor devices will be closed. So us e this command if you are sure that there are no important data to save!

Syntax:

usr forcedreturn <command_parameters>

Possible <command_parameters>:

-d DriveLetter	Forcibly returns a device by its DriveLetter. You can specify just a drive letter ("C"), a drive letter and ":" ("C:") as well as a path to a folder or a file on the drive
-n DeviceName	Forcibly returns a device by its name (part of a name is also acceptable). "Name" - is those name which is displayed by usr list command

Examples:

"usr forcedreturn -d g:"	Forcibly returns a device that has drive g: back
"usr forcedreturn -n Sony"	Forcibly returns a device with word "Sony" in the name back

list

Displays the list of hot-plug devices

Syntax:

usr list [command_parameters]

Possible "command_parameters":

-a	Displays all hot-plug devices (by default)
-s	Displays only devices are allowed to be stopped (those that are displayed in the GUI version's stop menu)
-u	Displays only devices that are prohibited to be stopped (those that are hidden from the the GUI version's stop menu)

When there are no options defined the command displays all hot-plug devices (the same as with option "-a")

Examples:

"usr list"	Displays all hot-plug devices
"usr list -s"	Displays only showed in the stop menu devices

wholocks

Displays the list of processes that prevent a device from being stopped or returned back

If the device is stopped but not yet unplugged the command will return the list of processes locking neighbour devices at USB hub. On why it does this, read more here.

Syntax:

usr wholocks <command_parameters>:

Possible <command_parameters>:

-d DriveLetter	Finds a device by its DriveLetter and displays all processes that are locking it
-n DeviceName	Finds a device by its DeviceName (full or partial) and displays all processes that are locking it

Examples:

"usr wholocks -d g:"	Displays processes, which are locking the device that has drive g:
"usr wholocks -n Sony"	Displays processes that are locking a device with word "Sony" in the name

Back to contents