Shell Command Reference Manual

4BCommand Descriptions

Usage

CLS [color]

color - New background color

0 - Black

1 - Blue

2 - Green

3 - Cyan

4 - Red

5 - Magenta

6 - Yellow

7 - Light gray

Description

This command clears the standard output device with an optional background color attribute. If

color

is not defined, then the background color does not change.

Examples

Shell> help cls

Clears the standard output and optionally changes the background color.

CLS [color]

color - New background color

0 - Black

1 - Blue

2 - Green

3 - Cyan

4 - Red

5 - Magenta

6 - Yellow

7 - Light gray

Note:

1. If no parameters are specified, this command clears the standard

output device. The background color is not changed.

Examples:

* To clear standard output without changing the background color:

fs0:\> cls

* To clear standard output and change the background color to cyan:

fs0:\> cls 3

* To clear standard output and change the background to the default color: fs0:\> cls 0

2.2.5 connect

Summary

Binds a driver to a specific device and starts the driver.

EFI Versions

EFI 1.10 and above.

16

Usage

CONNECT [[DeviceHandle] [DriverHandle] | [-c] | [-r]]

-r - Connect recursively

-c - Connect console devices described in the EFI

Environment Variables

DeviceHandle - Device handle, always taken as hexadecimal number

DriverHandle - Driver handle, always taken as hexadecimal number

Description

This command binds a driver to a specific device and starts the driver. If the

-r

flag is used, then the connection is done recursively until no further connections between devices and drivers are made. If the

-c

flag is used, then the

connect

command will bind the proper drivers to the console devices that are described in the EFI environment variables. The example below shows the typical output from the verbose help for this command.

17

4BCommand Descriptions

Examples

Shell> help connect

Connects one or more EFI drivers to a device.

CONNECT [[DeviceHandle] [DriverHandle] | [-c] | [-r]]

DeviceHandle - Device handle in hexadecimal format

DriverHandle - Driver handle in hexadecimal format

-c - Connect console devices

-r - Connect recursively

Note:

1. If no 'DeviceHandle' parameter is specified, all device handles

in the current system will be the default.

2. If no 'DriverHandle' parameter is specified, all matched drivers

will be bound to the specified device.

3. If 'DriverHandle' parameter is provided, the specified driver

will have highest priority on connecting the device(s).

4. If the '-c' option is specified, only console devices described

in the EFI Shell environment variables and related devices will

be connected.

5. If the '-r' option is specified, the command will recursively

scan all handles and check to see if any loaded or embedded

driver can match the specified device. If so, the driver will be

bound to the device.

Additionally, if more device handles are created during the

binding, these handles will also be checked to see if a matching

driver can bind to these devices as well. The process is

repeated until no more drivers are able to connect to any

devices. However, without the option, the newly created device

handles will not be further bound to any drivers.

6. If only a single handle is specified and the handle has an

EFI_DRIVER_BINDING_PROTOCOL on it, then the handle is assumed to

be a driver handle. Otherwise, it is assumed to be a device

handle.

7. If no parameters are specified, then the command will attempt to

bind all proper drivers to all devices without recursion. Each

connection status will be displayed.

8. Output redirection is not supported for 'connect -r' usage.

Examples:

* To connect all drivers to all devices recursively:

Shell> connect -r

* To display all connections:

Shell> connect

ConnectController(1) : Status = Success

ConnectController(2) : Status = Success

ConnectController(3) : Status = Success

...

ConnectController(3D) : Status = Success

* To connect drivers with 0x17 as highest priority to all the devices

they can manage:

Shell> connect 17

* To connect all possible drivers to device 0x19:

Shell> connect 19

* To connect drivers with 0x17 as highest priority to device 0x19

they can manage:

Shell> connect 19 17

* To connect console devices described in the EFI Shell environment

variables:

Shell> connect -c

18

2.2.6 cp

Summary

Copies one or more source files or directories to a destination.

EFI Versions

EFI 1.02 and above.

Usage

CP [-r] [-q] src [src...] [dst]

-r - Recursive copy

-q - Quiet copying (replace existing files without

prompt)

src - Source file/directory name (wildcards are

permitted)

dst - Destination file/directory name (wildcards are not

permitted)

Description

This command copies one or more source files or directories to a destination. If the source is a directory, the

-r

flag must be specified. If

-r

is specified, then the source directory will be recursively copied to the destination (which means that all subdirectories will be copied). If a destination is not specified, then the current working directory is assumed to be the destination.

If any target file (not directory) already exists, there will be a prompt asking the user to confirm replacing the file. The following four choices are available:

• Yes: Replace the file.

• No: Do not replace the file.

• All: Replace the existing files in all subsequent cases.

• Cancel: Do not replace any existing files in all subsequent cases.

If there are multiple source files/directories, the destination must be a directory.

19

4BCommand Descriptions

Examples

Shell> help cp

Copies one or more files/directories to another location.

CP [-r] [-q] src [src...] [dst]

-r - Recursive copy

-q - Quiet copying (replace existing files without

prompt)

src - Source file/directory name (wildcards are

permitted)

dst - Destination file/directory name (wildcards are not

permitted)

Note:

1. ‘-r’ must be specified if src is a directory. If '-r' is

specified, then the source directory will be recursively

copied to the destination.

Src itself will be copied.

2. If 'dst' parameter is not specified, then the current

directory is assumed to be the destination.

3. 'Cp -r src1 src2 dst' is to copy all files and subdirectories

in 'src1' and 'src2' to the destination 'dst'. 'Src1' and

'src2' themselves are also copied. 'dst' parameter will be

interpreted as a directory.

4. Copying a directory/file to itself is not allowed.

5. If an error occurs, Cp will exit immediately and the remaining

files or directories will not be copied.

6. When 'cp' is executed with a script file, it always performs

Quiet copy regardless of whether the '-q' option is specified.

7. If you are copying multiple files, the destination must be an

existing directory.

Examples:

* To display the contents of current directory first of all:

fs0:\> ls

Directory of: fs0:\

06/18/01 01:02p <DIR> 512 efi

06/18/01 01:02p <DIR> 512 test1

06/18/01 01:02p <DIR> 512 test2

06/13/01 10:00a 28,739 IsaBus.efi

06/13/01 10:00a 32,838 IsaSerial.efi

06/18/01 08:04p 29 temp.txt

06/18/01 08:05p <DIR> 512 test

3 File(s) 61,606 bytes

4 Dir(s)

* To copy a file in the same directory, but change the file

name:

fs0:\> cp temp.txt readme.txt

copying fs0:\temp.txt -> fs0:\readme.txt

- [ok]

* To copy multiple files to another directory:

fs0:\> cp temp.txt isaBus.efi \test

copying fs0:\temp.txt -> fs0:\test\temp.txt

- [ok]

copying fs0:\isaBus.efi -> fs0:\test\IsaBus.efi

- [ok]

* To copy multiple directories recursively to another

directory:

fs0:\> cp -r test1 test2 boot \test

copying fs0:\test1 -> fs0:\test\test1

copying fs0:\test1\test1.txt -> fs0:\test\test1\test1.txt

- [ok]

20

copying fs0:\test2 -> fs0:\test\test2

copying fs0:\test2\test2.txt -> fs0:\test\test2\test2.txt

- [ok]

copying fs0:\boot -> fs0:\test\boot

copying fs0:\boot\shell.efi -> fs0:\test\boot\shell.efi

- [ok]

* To see the results of the above operations:

fs0:\> ls \test

Directory of: fs0:\test

06/18/01 01:01p <DIR> 512 .

06/18/01 01:01p <DIR> 0 ..

01/28/01 08:21p <DIR> 512 test1

01/28/01 08:21p <DIR> 512 test2

01/28/01 08:21p <DIR> 512 boot

01/28/01 08:23p 29 temp.txt

01/28/01 08:23p 28,739 IsaBus.efi

2 File(s) 28,828 bytes

5 Dir(s)

Shell>

2.2.7 date

Summary

Displays and sets the current date for the system.

EFI Versions

EFI 1.02 and above.

Usage

DATE [mm/dd/[yy]yy]

mm - Month of date to be set, Month range: 1 – 12

dd - Day of date to be set, Day range: 1 – 31

yyyy - Year of date to be set, Year range: 1998 – 2099

Description

This command displays and/or sets the current date for the system. If no parameters are used, it shows the current date. If a valid month, day, and year are provided, then the system's date will be updated. Detailed rules are listed below:

1. Except for numeric characters and /, all other characters in the argument are invalid. The Shell will report an error if the number is in the wrong month/date/year range.

2. Space before or after the numeric character is not allowed. Inserting a space into the number is invalid.

3. Repeated zeros are allowed before the number. For example:

21

4BCommand Descriptions

Shell > date 0000008/000004/000097

Shell > date

08/04/2097

Shell >

4. The year range is greater than or equal to 1998. Two numeric characters indicate the year. Numbers below 98 are regarded as 20xx, and numbers equal to or above 98 are regarded as 19xx. 00 means 2000. For example:

Shell > date 8/4/97

Shell > date

08/04/2097

Shell >

Shell > date 8/4/98

Shell > date

08/04/1998

Shell >

5. The range of valid years is from 1998–2099.

Examples

Shell> help date

Displays the current date or sets the date in the system.

DATE [mm/dd/[yy]yy]

mm - Month of date to be set, Month range: 1 - 12

dd - Day of date to be set, Day range: 1 - 31

yyyy - Year of date to be set, Year range: 1998 - 2099

Note:

1. yy: 98=1998, 99=1999, 00=2000, 01=2001, ..., 97=2097.

2. yyyy: 1998 - 2099, other values are invalid.

3. EFI may behave unpredictably if illegal date values are used.

Examples:

* To display the current date in the system:

fs0:\> date

06/18/2001

* To set the date with long year format:

fs0:\> date 01/01/2050

fs0:\> date

01/01/2050

* To set the date with short year format:

fs0:\> date 06/18/01

fs0:\> date

06/18/2001

Shell>

2.2.8

Summary del

Deletes one or more files or directories.

22

EFI Versions

EFI 1.02 and above.

Usage

DEL [-q] file/directory [file/directory ...]

-q - Quiet mode; does not prompt user for a confirmation

file - File name (wildcards are permitted)

directory - Directory name (wildcards are permitted)

Description

This command deletes one or more files or directories. If the target is a directory, it will delete the directory, including all its subdirectories. It is not allowed to redirect a file whose parent directory (or the file itself) is being deleted.

23

4BCommand Descriptions

Examples

Shell> help del

Deletes one or more files or directories.

DEL [-q] file/directory [file/directory ...]

-q - Quite mode; does not prompt user for a

confirmation

file - File name (wildcards are permitted)

directory - Directory name (wildcards are permitted)

Note:

1. Removing a read-only file/directory will result in a failure.

Removing a directory containing read-only file(s) will result

in a failure.

2. If an error occurs, DEL will exit immediately and later

files/directories will not be removed.

3. You cannot remove a directory when the current directory is

itself or its subdirectory.

4. If file contains wildcards, it will not ask user for

confirmation.

5. You cannot remove the root directory.

6. You cannot remove the current directory or its ancestor.

7. Redirecting output to a file that exists under the directory

that will be removed is not allowed.

Examples:

* To remove multiple directories at a time:

fs0:\> ls test

Directory of: fs0:\test

06/18/01 01:01p <DIR> 512 .

06/18/01 01:01p <DIR> 0 ..

06/19/01 12:59a <DIR> 512 temp1

06/19/01 12:59a <DIR> 512 temp2

0 File(s) 0 bytes

4 Dir(s)

* Error occurs and DEL will exit:

fs0:\> del test\temp11 temp2

rm/del: Cannot find 'fs0:\test\temp11' - Not Found

* To remove multiple directories with wildcards:

fs0:\> del test\temp*

rm/del: Remove subtree 'fs0:\test\temp1' [y/n]? y

removing fs0:\test\temp1\temp1.txt

- [ok]

removing fs0:\test\temp1\boot\nshell.efi

- [ok]

removing fs0:\test\temp1\boot

- [ok]

removing fs0:\test\temp1

- [ok]

rm/del: Remove subtree 'fs0:\test\temp2' [y/n]? y

removing fs0:\test\temp2\temp2.txt

- [ok]

removing fs0:\test\temp2

- [ok]

* Removing a directory that contains a read-only file will

fail:

fs0:\> attrib +r test\temp1\readme.txt

A R fs0:\test\temp1\readme.txt

fs0:\> del test\temp1

rm/del: Cannot open 'readme.txt' under 'fs0:\test\temp1' in

24

writable mode

- [error] - Access Denied

Exit status code: Access Denied

Shell>

2.2.9 dh

Summary

Displays the device handles in the EFI environment.

EFI Versions

EFI 1.10 and above.

Usage

DH [-l <lang>] [handle | -p <prot_id>] [-d] [-v]

handle - Dumps information of a specified handle, always

taken as hexadecimal number

-p - Dumps all handles of a protocol specified by

prot_id

-d - Dumps EFI Driver Model related information

-l - Dumps information using the ISO 639-2 language

specified by lang.

-v - Dumps verbose information on specified handle

Description

This command displays the device handles in the EFI environment. If this command is used with a specific handle number, the details of all the protocols that are associated with that device handle are displayed. Otherwise, the

-p

option can be used to list the

device handles that contain a specific protocol. See Supported EFI Protocols in the

Shell

for the abbreviations that are used with this command for EFI protocols. The following examples show how the command can be used.

25

4BCommand Descriptions

Examples

Shell> help dh

Displays the handles in the EFI environment.

DH [-l <lang>] [handle | -p <prot_id>] [-d] [-v]

handle - Dumps information of a specified handle,

always taken as hexadecimal number

-p - Dumps all handles of a protocol specified by

prot_id

-d - Dumps EFI Driver Model related information

-l - Dumps information using the ISO 639-2 language

specified by lang.

-v - Dumps verbose information on specified handle

Note:

1. When neither 'handle' nor 'prot_id' is specified, a list of

all the handles in the EFI environment is displayed.

2. Option '-d' can be used to display EFI Driver Model related

information, including its parent handles, child handles, all

drivers on it, etc.

3. Option '-v' can be used to display verbose information on the

specified handle, including all the protocols on it and their

details.

4. If option '-p' is specified, all handles containing the

specified protocol will be displayed. Otherwise, the 'handle'

parameter has to be specified for display. In this case,

option '-d' will be enabled automatically if option '-v' is

not specified.

Examples:

* To display all handles and display one screen at a time:

Shell> dh -b

Handle dump

1: Image(DXE Core)

2: FwVol FwFileSys FwVolBlk DevPath(MemMap(11:1B50000-

1D4FFC8))

3: Image(Ebc)

4: DevPath(MemMap(11:1CA0000-1CB0000))

5: Image(WinNtThunk)

6: WinNtThunk DevPath(..76F3-11D4-BCEA-0080C73C8881))

7: Image(WinNtBusDriver) DriverBinding

...

* To display the detailed information on handle 0x30:

Shell> dh 30

Handle 30 (01AF5308)

IsaIo

ROM Size......: 00000000

ROM Location..: 00000000

ISA Resource List :

IO : 000003F8-000003FF Attr : 00000000

INT : 00000004-00000000 Attr : 00000000

dpath

PNP Device Path for PnP

HID A0341D0, UID 0x0

Hardware Device Path for PCI

PNP Device Path for PnP

HID 50141D0, UID 0

AsStr: 'Acpi(PNP0A03,0)/Pci(1F|0)/Acpi(PNP0501,0)'

* To display all handles with 'diskio' protocol:

Shell> dh -p diskio

Handle dump by protocol 'Diskio'

15: DiskIo BlkIo DevPath(..i(3|1)/Ata(Secondary,Master))

26

16: DiskIo BlkIo DevPath(..,1)/PCI(0|0)/Scsi(Pun0,Lun0))

44: DiskIo BlkIo Fs DevPath(..ABD0-01C0-507B-9E5F8078F531))

ESP

45: DiskIo BlkIo Fs DevPath(..i(Pun0,Lun0)/HD(Part4,SigG0))

ESP

17: DiskIo BlkIo DevPath(..PCI(3|1)/Ata(Primary,Master))

* To display all handles with 'Image' protocol and break when

the screen is full:

Shell> dh -p Image -b

Handle dump by protocol 'image'

1: Image(DXE Core)

5: Image(WinNtThunk)

7: Image(WinNtBusDriver) DriverBinding

8: Image(Metronome)

A: Image(IsaBus) DriverBinding

B: Image(WinNtConsole) DriverBinding

...

Shell>

2.2.10 dir

Summary

Lists directory contents or file information.

EFI Versions

EFI 1.02 and above.

Usage

DIR [-r] [-a[attrib]] [file]

-r - Displays recursively (including subdirectories)

attrib - 'a', 's', 'h', 'r', 'd' or combination of them

a - Archive

s - System

h - Hidden

r - Read-only

d - Directory

file - Name of file/directory (wildcards are permitted)

Description

This command lists directory contents or file information. If no file name or directory name is specified, then the current directory is assumed. The contents of a directory are listed if all of the following are true:

• If option

-r

is not specified

• If no wildcard characters are specified in the

file

parameter

• If

file

represents an existing directory

In all other cases, the command functions as follows:

27

4BCommand Descriptions

• All files/directories that match the specified name are displayed.

• The

-r

flag determines whether a recursive search is performed.

• The option flag

-a[attrib]

tells the command to display only those files with the attributes that are specified by

[attrib]

. If more than one attribute is specified, only the files that have all those attributes will be listed. If

-a

is followed by nothing, then all files/directories are displayed, regardless of their attributes. If

-a

itself is not specified, then all files except system and hidden files are displayed.

28

Examples

Shell> help dir

Displays a list of files and subdirectories in a directory.

DIR [-r] [-a[attrib]] [file]

-r - Displays recursively (including subdirectories)

attrib - 'a', 's', 'h', 'r', 'd' or combination of them

a - Archive

s - System

h - Hidden

r - Read-only

d - Directory

file - Name of file/directory (wildcards are permitted)

Examples:

* To hide files by adding the hidden or system attribute to

them:

fs0:\> attrib +s +h *.efi

ASH fs0:\IsaBus.efi

ASH fs0:\IsaSerial.efi

* To display all, except the files/directories with 'h' or 's'

attribute:

fs0:\> dir

Directory of: fs0:\

06/18/01 09:32p 153 for.nsh

06/18/01 01:02p <DIR> 512 efi

06/18/01 01:02p <DIR> 512 test1

06/18/01 01:02p <DIR> 512 test2

06/18/01 08:04p 29 temp.txt

06/18/01 08:05p <DIR> 512 test

01/28/01 08:24p r 29 readme.txt

3 File(s) 211 bytes

4 Dir(s)

* To display files with all attributes in the current

directory:

fs0:\> dir -a

Directory of: fs0:\

06/18/01 09:32p 153 for.nsh

06/18/01 01:02p <DIR> 512 efi

06/18/01 01:02p <DIR> 512 test1

06/18/01 01:02p <DIR> 512 test2

06/18/01 10:59p 28,739 IsaBus.efi

06/18/01 10:59p 32,838 IsaSerial.efi

06/18/01 08:04p 29 temp.txt

06/18/01 08:05p <DIR> 512 test

01/28/01 08:24p r 29 readme.txt

5 File(s) 61,788 bytes

4 Dir(s)

* To display files with read-only attributes in the current

directory:

fs0:\> dir -ar

Directory of: fs0:\

06/18/01 11:14p r 29 readme.txt

1 File(s) 29 bytes

0 Dir(s)

29