AmigaOS Manual: AmigaDOS Command Reference

The commands in this chapter are executed from the Shell window. They are described in alphabetic order; however, some commands reserved for system use appear together at the end of the chapter.

Command Documentation

Each command documented in this manual is shown with the format, arguments, options, symbols, and abbreviations required for proper use.

This chapter and Chapter 7 provide command specifications for the AmigaDOS commands and the Workbench programs accessible through the Shell using the following standard outline:

Format

All the arguments and options accepted by a command. The special characters that indicate the particular type of argument are described on page 6-6.

Template

An optional on-line reminder of the command's format that is embedded in the program's code. Entering a command followed by a space and a question mark (for example, DIR ?) displays the template. A complete description of the template notation is found on page 6-8.

Location

The directory where the command is normally stored.

Examples

A sample use of the command. Examples are displayed in the courier typeface to distinguish them from normal text. The 1> represents the Shell prompt; do not type it as part of the example command. Lines in the example not prefaced by 1> represent the output of a command. Command names and keywords are shown in all upper case letters and file and directory names usually have the first letter in upper case; however, they do not need to be entered that way. Press Return to execute the command line.

Separate commands and arguments with spaces. Use punctuation only when required in the syntax of specific commands.

Format

The following lists the characters that indicate the type of argument shown in format listings. Do not use these characters as part of the command.

< >	Angle brackets indicate where additional information, such as a file name, must be included. This argument is required if it is not surrounded by square brackets. (For example, [<filename>]; see below.)
[ ]	Square brackets enclose optional arguments and keywords. Although not required, these arguments and keywords are accepted by the command.
{ }	Braces enclose items that can be given once or repeated any number of times. For example, {<args>} indicates that several items can be given for this argument.
|	Vertical bars separate lists of options from which you can choose only one. For example, [OPT R|S|RS] indicates a choice of the R option, the S option, or both options.
<n>	A numeric value is expected by the argument.
KEYWORD	Italics indicate that the argument's keyword is required if you include that argument.
...	An ellipsis (...) after a string argument indicates that the string must be the final argument on the command line. Including a comment is not allowed. The remainder of the command line is taken as the desired string. Quotation marks are not needed around the string, even if it contains spaces. If you enter quotation marks, they are part of the string. If you specify the keyword, you can put leading and trailing spaces in the string.
command line indentation	On command lines that are long enough to wrap to the next line, this manual shows the wrapped lines as indented for documentation purposes only. In practice, the wrapped lines align with the first character of the Shell prompt.

The format for the COPY command illustrates the use of these conventions:

COPY [FROM] {<name | pattern>} [TO]<name | pattern>[ALL]
   [QUIET] [BUF | BUFFER=<n>] [CLONE] [DATES] [NOPRO]
   [COM] [NOREQ]

The [FROM] keyword is optional. If it is not specified, the command reads the file name ir pattern to copy by ist position on the command line.

The {<name | pattern>} argument must be provided. You must substitute either a file name or pattern. The braces indicate that more than one name or pattern can be given.

The [TO] keyword is optional. If it is not specified, the command reads the file name or device to copy to by its position on the command line.

The <name | pattern> argument must be provided. You can specify only one destination.

The [ALL], [QUIET], [CLONE], [DATES], [NOPRO], [COM], and [NOREQ] arguments are optional.

The [BUF | BUFFER=<n>] argument is optional. If given, the keyword is required, but you can use either BUF or BUFFER with the numerical argument. For example, both BUF=5 and BUFFER=5 are acceptable. The numerical argument can also be entered without the equals sign; spaces are optional.

Template

The Template is built into the system to serve as an on-line reminder of a command's syntax and to let you run the command from the Template line by providing a prompt at which you enter the command's arguments.

Display the Template by entering a question mark (?) after a command. The Shell assumes that you wish to run the command and it expects you to enter the command's arguments after the colon following the display. For example:

1> TYPE ?
FROM/A/M,TO/K,OPT/K,HEX/S,NUMBER/S:

Pressing Return executes the command if it does not require any arguments to run properly. Entering the arguments and their respective keywords and then pressing Return also executes the command. If a command requires arguments and you do not supply them or if you enter anything other than the required arguments, pressing Return results in a non-fatal error message. Remember that you do not need to enter the entire format for a command at this prompt, just the required arguments.

The Templates are listed with the arguments separated by commas, followed by a slash (/), and a capital letter indicating the type of argument. These slash/letter combinations are displayed to remind you of the command's particular requirements and are not entered as part of the command. The following table explains the notation:

Template Notation	Format Equivalent	Meaning
argument/A	<name>	The argument is always required.
option/K	KEYWORD	The option's keyword is required if the argument is given.
option/S	[KEYWORD]	The option works as a switch. The name of the option must be entered to specify it. Most options are switches.
value/N	<n>	The argument is numeric.
argument/M	{<name>}	Multiple items are accepted for this argument. Although there is no limit to the number of possible arguments, they must be provided before the next argument or option.
string/F	argument...	The string must be the final argument on the command line; the remainder of the command line is taken as the desired string.
=	KYWD | KEYWORD	Two different forms of the keyword are equivalent and either are accepted. The equals sign is not entered as part of the command.

The Template for the COPY command illustrates the use of arguments:

FROM/M,TO/A,ALL/S,QUIET/S,BUF=BUFFER/K/N,
CLONE/S,DATES/S,NOPRO/S,COM/S,NOREQ/S

FROM/M indicates that the argument is required and more than one argument is acceptable.

TO/A indicates that the argument is required.

ALL/S, QUIET/S, CLONE/S, DATES/S, NOPRO/S, COM/S, and NOREQ/S indicate that the keywords act as switches. If the keyword is present in the line, the option is used.

BUF=BUFFER/K/N indicates that the BUF or BUFFER keyword (/K) is required to specify this numerical (/N) argument. Both BUF and BUFFER are acceptable keywords (=).

Keywords and their arguments can be linked with an equals sign (=) to ensure correct assignments in complex cases. For example, BUF=20.

Command Listing

ADDBUFFERS

Instructs the file system to add or display cache buffers for a drive.

Format

ADDBUFFERS <drive> [<n>]

Template

DRIVE/A,BUFFERS/N

Location

C:

ADDBUFFERS adds <n> buffers to the list of buffers available for <drive>. Although adding buffers speeds disk access, each additional buffer reduces free memory by approximately 512 bytes. The default buffer allocation is 5 for sloppy drives and 30 for hard disk partitions.

The amount of extra available memory dictates the number of buffers you can add. There is no fixed upper limit; however, adding too many buffers reduces overall system performance by taking RAM away from other system functions. Specifying a negative number subtracts that many buffers from the current allocation. The minimum number of buffers is one; however, using only one is not recommended.

Twenty buffers are recommended for a floppy drive in a 512 KB system. Use the default value recommended by the HDToolBox program for hard disks. (Display this value by selecting the Advanced Options gadget on the Partitioning screen.)

If only the <drive> argument is specified, ADDBUFFERS displays the number of buffers currently allocated for that drive.

Example

1> ADDBUFFERS DF0:
DF0: has 5 buffers

A further example of ADDBUFFERS appears in Chapter 8.

ALIAS

Sets or displays command aliases.

Format

ALIAS [<name>] [<string...>]

Template

NAME,STRING/F

Location

Internal

ALIAS creates aliases, or alternative names, for AmigaDOS commands. ALIAS can be used to abbreviate frequently used commands or replace standard command names with different names.

When AmigaDOS encounters <name>, it replaces it with the defined <string>, integrate the result with the rest of the command line, and attempts to interpret and execute the resulting line as an AmigaDOS command <Name> is the alias for the command and <string> is the command to be substituted for the alias.

An alias must be entered at the beginning of the command line. You can enter arguments after the alias, but you cannot create an alias to represent a series of command arguments. For example, in the following command line:

1> NEWSHELL WINDOW=CON:0/250/640/150/2SHELL/CLOSE

the WINDOW argument cannot be replaced with an alias.

You can substitute a file name or other instruction within an alias by placing square brackets ([ ]) with nothing between them in the <string>. Any argument entered after the alias is inserted at the brackets.

ALIAS <name> displays the <string> for that alias. Entering ALIAS alone lists all current aliases.

Aliases are local to the Shell in which they are defined. If you create another Shell with the NEWSHELL command, it shares the same aliases as its parent Shell. However, if you create another Shell with the Execute Command menu item, it des not recognize aliases created in your original Shell. A global lais that is recognized by all Shells can be crated by inserting the alias in the Shell-startup file.

To remove an ALIAS, use the UNALIAS command.

Example 1

1> ALIAS d1 DIR DF1:

Entering d1 displays a directory of the contents of the disk in DF1:; as if you entered DIR DF1:.

Example 2

1> ALIAS hex TYPE [ ] HEX

creates an alias called HEX that displays the contents of a specified file in hexadecimal format. The empty brackets indicate where the file name is inserted in this example. Entering:

1> hex Myfile

displays the contents of Myfile in hexadecimal format.

See also: UNALIAS. Further examples of using ALIAS appear in Chapter 8.

ASK

Gets yes or no user input during script file execution.

Format

ASK <prompt>

Template

PROMPT/A

Location

Internal

ASK is used in scripts to write the string specified by <prompt> to the current window and then wait for keyboard input. Valid keyboard responses are Y (yes), N (no), and Return (no). Selecting Y sets the condition flag to 5 (WARN). Selecting N or pressing Return sets the condition flag to 0. Check the response using an IF statement.

If the <prompt> contains spaces, it must be enclosed in quotation marks.

Example

Assume a script contained the following commands:

ASK Continue?
IF WARN
   ECHO Yes
ELSE
   ECHO No
ENDIF

At the ASK command, Continue? Is displayed on the screen. If Y is pressed, Yes is displayed on the screen. If N or a Return alone is pressed, No is displayed.

See also: IF, ELSE, ENDIF, REQUESTCHOICE, WARN

ASSIGN

Controls assignment of logical device names to files or directories.

Format

ASSIGN [<name>:] [{<target>}] [LIST] [EXISTS] [DISMOUNT] [DEFER] [PATH] [ADD] [REMOVE] [VOLS] [DIRS] [DEVICES]

Template

NAME,TARGET/M,LIST/S,EXISTS/;,DISMOUNT/S,DEFER/S,PATH/S,ADD/S,REMOVE/S,VOLS/S,DIRS/S,DEVICES/S

Location

C:

ASSIGN allows references to files or directories with short, convenient logical device names, rather than their usual names or complete paths. The ASSIGN command can create assignments, remove assignments, or list some or all current assignments.

If the <name> and {<target>} arguments are given, ASSIGN assigns the given logical name to the specified target. Each time the assigned logical device name is referred to, AmigaDOS accesses the specified target. If the <name> given is already assigned to a file or directory, the new target replaces the previous one. A colon must be included after the <name> argument.

If only the <name> argument is given, any existing ASSIGN of a file or directory to that logical device name is cancelled.

You can assign several logical device names to the same target by using multiple ASSIGN commands.

You can assign one logical device name to several targets by specifying each file or directory after the <name> argument or by using several ASSIGN commands with the ADD option. Specifying the ADD option does not replace any existing target assigned to <name>. This target is added to the ASSIGN list and the system searches for all the targets when <name> is encountered. If the first target is not available, ASSIGN uses the next target added.

The REMOVE option deletes a target name from the ASSIGN list.

If no arguments are given with ASSIGN or if the LIST keyword is used, a list of all current assignments is displayed. If the VOLS, DIRS, or DEVICES switch is specified, ASSIGN limits the display to volumes, directories, or devices.

When the EXISTS keyword is entered with a logical device name, AmigaDOS searches the ASSIGN list for that name and displays the volume and directory assigned to that device. If the device name is not found, the condition flag is set to 5 (WARN).

When the {<target>} argument is given, AmigaDOS immediately looks for that file or directory. If the ASSIGN commands are part of the User-startup, the targets must be present on a mounted disk during the boot procedure. If an assigned target cannot be found, a requester asks for the volume containing it. However, using the DEFER and PATH options make the system wait until the target is needed before searching for it.

Note
The assigned name does not have to retain the name of the file or directory and it does not have to be in upper case. For example, the name CLIPS: or Clips: can be assigned to the Ram Disk:Clipboards directory.

The DEFER option creates a late-binding ASSIGN. This ASSIGN takes effect when the assigned object is first referenced, rather than when the assignment is made. When the DEFER option is used, the disk containing the assigned target is not needed until the object is called. The assignment then remains valid until explicitly changed.

If you ASSIGN FONTS: to DF0:Fonts with the DEFER option, the system associates FONTS: with the disk that is in DF0: when FONTS: is referred to. For example, if you have a Workbench disk in DF0: at the time the FONTS: directory is needed, the system associates FONTS: with that particular Workbench disk. If you later remove that Workbench disk and insert another disk containing a Fonts directory, the system specifically requests the original Workbench disk the next time FONTS: is needed.

The PATH option creates a non-binding ASSIGN. A non-binding ASSIGN acts like a DEFERed ASSIGN, except that is re-evaluated each time the assigned name is referenced. For example, if you assign FONTS: to DF0:Fonts with the PATH option, any disk in DF0: is searched when FONTS: is referenced. As long as the disk contains a Fonts directory, it satisfies the ASSIGN. You cannot assign multiple directories with the PATH option.

Floppy disk only system users can find that using the PATH option eliminates the need to reinsert the original Workbench disk used to boot the system. As long as the drive you assigned with the PATH option contains a disk with the assigned directory name, the system uses that disk.

The DISMOUNT option disconnects a volume or device from the list of mounted devices. You must provide the device name in the argument. DISMOUNT removes the name form the list, but does not free resources. You cannot cancel a DISMOUNT without rebooting. DISMOUNT is meant for use by software developers only and can cause a software failure if not used carefully.

Example 1

1> ASSIGN FONTS: MyFonts:Fontdir

assigns the FONTS: directory to Fontdir on MyFonts:

Example 2

1> ASSIGN LIST
Volumes:
Ram Disk [Mounted]
Workbench [Mounted]
MyFonts [Mounted]

Directories:
LOCALE Workbench:Locale
KEYMAPS Workbench:Devs/Keymaps
PRINTERS Workbench:Devs/Printers
REXX Workbench:S
CLIPS Ram Disk:Clipboards
ENV Ram Disk:Env
T Ram Disk:T
ENVARC Workbench:Prefs/Env-Archive
SYS Workbench:
C Workbench:C
S Workbench:S
L Workbench:L
FONTS MyFonts:Fontdir
DEVS Workbench:Devs
LIBS Workbench:Libs
+ Workbench:Classes

Devices:
PIPE AUX RAM CON
RAW PAR SER PRT DF0

Shows a typical list of all current assignments. The plus sign indicates any additional directories with the same assignment.

Example 3

1> ASSIGN FONTS: EXISTS
FONTS: MyFonts:FontDir

is an inquiry into the assignment of FONTS:. AmigaDOS responds by showing that FONTS: is assigned to the FontDir directory of the MyFonts volume. The return code is set to 0 if it exists or to 5 if it does not.

Example 4

1> ASSIGN LIBS: SYS:Libs BigAssem:Libs ADD

is a multiple-directory assignment that creates a search path containing two Libs directories. Specifying ADD keeps the standard SYS:Classes assignment from being removed. These directories are searched in sequence each time LIBS: is invoked.

Example 5

1> ASSIGN DEVS:

removes the DEVS: assignment from the system.

Example 6

1> ASSIGN WorkDisk: DF0: DEFER
1> ASSIGN WorkDisk: EXISTS
WorkDisk <DF0:>

sets up a late-binding assignment of the logical device WorkDisk:. Until the first time you refer to the name WorkDisk:, you do not need to insert it in DF0: ASSIGN shows DF0: enclosed in angle brackets to indicate that it is DEFERred. After the first reference to WorkDisk:, the volume name of the disk that was in DF0: replaces <DF0:>.

Example 7

1> ASSIGN C: DF0:C PATH
1> ASSIGN C: EXISTS
C [Df0: C]

references the C directory fo the disk that is in DF0: when a command is searched for. ASSIGN shows DF0:C in square brackets to indicate that it is a non-binding ASSIGN.

Example 8

1> ASSIGN LIBS: Zcad:Libs ADD

adds Zcad:Libs to the list of directories assigned as LIBS:.

Example 9

1> ASSIGN LIBS: Zcad:Libs REMOVE

removes Zcad:Libs from the list of directories assigned as LIBS:.

For more examples using ASSIGN, see Chapter 8.

AVAIL

Reports the amount of Chip and Fast memory available.

Format

AVAIL [VHIP | FAST | TOTAL] [FLUSH]

Template

CHIPS/S,FAST/S,TOTAL/S,FLUSH/S

Location

C:

AVAIL gives a summary of the system RAM, both Chip and Fast. For each memory type, AVAIL reports the total amount of memory, how much is available, how much is currently in use, and the largest contiguous memory block not yet allocated.

Unless you want a complete summary, use the CHIP, FAST, and/or TOTAL options to have AVAIL display only the number of free bytes of Chip, Fast, or Total RAM available.

The FLUSH option frees memory by removing all unused libraries, devices, fonts, catalogs.

Example 1

1> AVAIL
Type Available In-Use Maximum Largest
chip 233592 282272 515864 76792
fast 341384 182896 524280 197360
total 574976 465168 1040144 197360

A complete summary of system RAM is displayed.

Example 2

1> AVAIL CHIP
233592

The number of free bytes of Chip RAM is displayed.

See Chapter 8 for more examples using AVAIL.

BREAK

Sets attention flags in the specified process.

Format

BREAK <process> [ALL | C | D | E | F]

Template

PROCESS/A/N,ALL/S,C/S,D/S,E/S,F/S

Location

C:

BREAK sets the specified attention flags in the <process> indicated. Use the STATUS command to display the current process numbers. C sets the Ctrl+C flag, D sets the Ctrl+D flag, and so on, ALL sets all the flags from Ctrl+C to Ctrl+F. By default, only the Ctrl+C flag is set.

BREAK acts the same as selecting the relevant process by clicking in its window and pressing the appropriate Ctrl+key combinations.

Ctrl+C is the default for sending a BREAK signal to halt a process. A process that has been aborted this way displays ***Break in the Shell window. Ctrl+D halts execution of a script file. The STATUS command displays the current process numbers. Ctrl+E is undefined.

Ctrl+F is used by programs that open windows to activate their window and bring it to the front of all windows. Not all programs respond to Ctrl+F.

Example 1

1> BREAK 7

sets the Ctrl+C attention flag of process 7. This is the same as selecting process 7 and pressing Ctrl+C.

Example 2

1> BREAK 5 D

sets the Ctrl+D attention flag of process 5.

See also: STATUS

CD

Sets or displays the current directory.

Format

CD [<dir | pattern>]

Template

DIR

Location

Internal

CD with no arguments displays the name of the current directory. When a valid directory name is given, CD makes the named directory the current directory.

You must specify a complete path to the directory since CD does not search through the disk for it. If CD cannot find the specified directory in the current directory or in the given path, a Can't find <directory> message is displayed.

To move up a level in the filing hierarchy to the parent directory of the current directory, enter CD followed by a space and a single slash (/). You can move to another directory in the parent at the same time by including its name after the slash. If the current directory is a root directory, CD / has no effect. Use multiple slashes with no spaces between them to refer to additional higher levels.

To move directly to the root directory of the current device, use CD followed by a space and a colon; for example, CD :

AmigaDOS supports an implied CD so that the CD command itself can often be left out. Enter the directory name, path, colon, or slashes at the prompt.

CD also supports pattern matching. When a directory matching the specified pattern is found, it becomes the current directory. If more than one directory matches the given pattern, an error message is displayed. You cannot use pattern matching with implied CD. For more information an pattern matching, see Chapter 3.

Example 1

1> CD DF1:Work

sets the current directory to the Work directory on the disk in drive DF1:.

Example 2

1> CD SYS:Com/Basic

makes the subdirectory Basic in the Com directory the current directory.

Example 3

1> //

using the implied CD, moves up two levels in the directory structure.

Example 4

1> CD SYS:Li#?

uses the #? pattern to match with the LIBS: directory.

For more examples using the CD command, see Chapter 8.

CHANGETASKPRI

Changes the priority of a currently running process.

Format

CHANGETASKPRI <priority> [PROCESS <process number>]

Template

PRI=PRIORITY/A/N,PROCESS/K/N

Location

C:

CHANGETASKPRI changes the priority of the specified Shell process. If no process is specified, the current Shell process is assumed. Any shell process started from <process number> inherits its priority.

Use the STATUS command to display the current process numbers.

The range of acceptable values for <priority> is the integers from -128 to 127, with higher values yielding a higher priority (a greater proportion of CPU time is allocated). However, do not enter values above +10 to avoid disrupting important system tasks.

Example

1> CHANGETASKPRI 4 Process 2

The priority of Process 2 is changed to 4. Any shell process started from this Shell also has a priority of 4. They have priority over any other user tasks created without using CHANGETASKPRI (those tasks have a priority of 0).

See also: STATUS. For another example for using CHANGETASKPRI, see Chapter 8.

COPY

Copies files or directories.

Format

COPY [FROM] {<name | pattern>} [TO] <name> [ALL] [quiet] [BUF | BUFFER=<n>] [CLONE] [DATES] [NOPRO] [COM] [NOREQ]

Template

FROM/M,TO/A,ALL/S,QUIET/S,BUF=BUFFER/K/N,CLONE/S,DATES/S,NOPRO/S,COM/S,NOREQ/S

Location

C:

COPY copies the file or directory specified with the FROM argument to the file or directory specified by the TO argument. You can copy several items at once by giving more than one name/pattern in the FROM argument; they should be separated by spaces. If the FROM argument is a pattern or consists of multiple names, the TO argument must be a directory.

If a TO file name already exists, COPY overwrites the TO file with the FROM file. You can use a pair of double quotation marks ("") to refer to the current directory. When used as the FROM argument, "" copies all the files in the current directory. Do not put any spaces between the double quotation marks.

If the FROM argument is a directory, only the directory's files are copied; its subdirectories are not copied. Use the ALL option to copy the complete directory, including its files, subdirectories, and the subdirectories' files. It is possible to create a directory as you copy if you are copying more than one file. To give the new directory a name, specify the directory name as the last component in the TO argument's path. This can be any name, including the same name as the original if it is a different path.

COPY prints to the screen the name of each file as it is copied. This can be overridden by the QUIET option.

The BUF= option is used to set the number of 512-byte buffers used during the copy. (Default is 128 buffers, 64 KB of RAM.) Limit the number of buffers when copying to RAM:. BUF=0 uses a buffer the same size as the file to be copied.

By default, COPY gives a TO file the timestamp of when the copy was made, rather than that of the original file. Also by default, comments attached to the original FROM file are not copied and the protection bits of the FROM file are copied to the TO file. You can override these defaults using the following:

CLONE	The timestamp, comments, and protection bits of the FROM file are copied to the TO file.
DATES	The timestamp of the FROM file is copied to the TO file.
COM	Any comment attached to the FROM file is copied to the TO file.
NOPRO	The protection bits of the FROM file are not copied to the TO file. The TO file is given standard protection bits or r, w, e, and d.

COPY displays a requester if the COPY cannot continue. When the NOREQ option is given, all requesters are suppressed. Use this in scripts to prevent a COPY failure from stopping the script to wait for a response. With the NOREQ option, the COPY command is aborted and the script continues.

Example 1

1> COPY File1 TO :Work/File2

copies File1 in the current directory to the Work directory in the root of the current device, renaming it File2.

Example 2

1> COPY Chapter#? TO DF1:Backup

copies all the files whose names start with Chapter in the current directory to the Bakkup directory on the disk in DF1:. The Backup directory is created if it does not already exist.

Example 3

1> COPY Work:Test TO " "

copies the files in the Test directory on Work to the current directory; subdirectories in Test are not copied.

Example 4

1> COPY Work:Test TO DF0:Test ALL

copies all the files and any subdirectories of the Test directory on Work to the Test directory on DF0:. If a Test directory does not already exist on DF0:, COPY creates one.

Example 5

1> COPY DF0: TO DF1: ALL QUIET

copies all files and directories on the disk in DF0: to DF1:, without displaying on the screen any file/directory names as they are copied. (For disks less than half full, this can be faster than DiskCopy.)

For more examples using COPY, see Chapter 8.