Introduction
User Interface
How to...
Order

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

What is the command line needed for?

USB Safely Remove'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:
  1. Data backup to an external backup HDD and its auto stopping
  2. A script that disables TrueCrypt (drive encryption tool) first and then stops the drive.
  3. 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%\USB Safely Remove\
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:

stopStops a device
returnReturns a device back
listDisplays the device list
wholocksDisplays the list of processes that prevent a device from being stopped or returned back
help <command_name>Displays help on <command_name> command
help errsDisplays the list of returned error codes (errorlevels)
helpDisplays 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

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

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 that has drive g: back
"usr return -n Sony" 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

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