Using the Command Line

This chapter includes:

• Command line or GUI?
• Processing a command
• Character-device drivers
• Shell
• Utilities
• Basic commands
• International keyboards
• Neutrino for MS-DOS users
• Troubleshooting

Command line or GUI?

Like QNX 4, UNIX, and DOS, Neutrino is based on a command-line interface. Although Neutrino includes an easy-to-use graphical interface (see the Using the Photon microGUI chapter), you'll likely have to type a command sometime -- especially if you're the system administrator. For information about choosing Photon or text mode, see the Controlling How Neutrino Starts chapter in this guide.

For developing software, you don't always have to use the command line; the QNX Momentics Professional Edition includes an Integrated Development Environment (IDE) that provides a graphical way to write, build, and test code. The IDE frequently uses Neutrino utilities, but "hides" the command line from you. For more information, see the IDE User's Guide.

If you want to use command lines from Photon, you can start a pterm terminal by clicking on the Terminal icon:

on the Photon shelf (located at the right edge of your workspace). You can run many terminals at once, each capable of running multitasking processes. Photon terminals emulate character devices, so the information in this chapter applies to them as well as to real character devices.

Processing a command

When you type a command, several different processes interpret it in turn:

1. The driver for your character device interprets such keys as Backspace and Ctrl-C.
2. The command interpreter or shell breaks the command line into tokens, interprets them, and then invokes any utilities.
3. The utilities parse the command line that the shell passes to them, and then they perform the appropriate actions.

Character-device drivers

When you type a command, the first process that interprets it is the character-device driver. The driver that you use depends on your hardware; for more information, see "Character I/O drivers (devc-*)" in the Utilities Summary of the Utilities Reference.

Some keys may behave differently from how they're described here, depending on how you configure your system.

For more information, see Character I/O in the System Architecture guide.

Input modes

Character-device drivers run in either raw input mode, or canonical (or edited input) mode. In raw input mode, each character is submitted to an application process as it's received; in edited input mode, the application process receives characters only after a whole line has been entered (usually signalled by a carriage return).

Terminal support

Some programs, such as vi, need to know just what your terminal can do, so that they can move the cursor, clear the screen, and so on. The TERM environment variable indicates the type of terminal that you're using, and the /usr/lib/terminfo directory is the terminal database. In this directory, you can find subdirectories (a through z) that contain the information for specific terminals. Some applications use /etc/termcap, the older single-file database model, instead of /usr/lib/terminfo.

The default terminal is qansi-m, the QNX version of an ANSI terminal. For more information about setting the terminal type, see "Terminal types" in Configuring Your Environment.

Telnet

If you're using telnet to communicate between two QNX machines (QNX 4 or Neutrino), use the -8 option to enable an eight-bit data path. If you're connecting to a Neutrino box from some other operating system, and the terminal isn't behaving properly, quit from telnet and start it again with the -8 option.

To telnet from Windows to a Neutrino machine, use ansi or vt100 for your terminal type.

The keyboard at a glance

The table below describes how the character-device drivers interpret various keys and keychords (groups of keys that you press simultaneously). The drivers handle these keys as soon as you type them.

Your keyboard might not behave as indicated if: The driver is in raw input mode instead of edited input mode. You're working with an application that has complex requirements for user interaction (e.g. the application might take control over how the keyboard works). or: You're working at a terminal that has keyboard limitations.

When you use the up or down arrow, the character-device driver passes a "back" or "forward" command to the shell, which recalls the actual command.

Physical and virtual consoles

The display adapter, the screen, and the system keyboard are collectively referred to as the physical console, which is controlled by a console driver.

Some systems don't include a console driver. For example, embedded systems might include only a serial driver (devc-ser*). The devc-con and devc-tcon drivers are currently supported only on x86 platforms.

To let you interact with several applications at once, Neutrino permits multiple sessions to be run concurrently by means of virtual consoles. These virtual consoles are usually named /dev/con1, /dev/con2, etc. Photon provides virtual consoles even if your system doesn't include a console driver; see Using the Photon microGUI.

When the system starts devc-con, it can specify how many virtual consoles to enable by specifying the -n. In a desktop system, the buildfile specifies four consoles when it starts diskboot. For more information, see the description of diskboot in the Controlling How Neutrino Starts chapter. The maximum number of virtual consoles is nine. The tiny console driver, devc-tcon, supports only one console.

The root user can also specify the program, if any, that's initially launched on each console. By default, the terminal-initialization utility (tinit) launches a login command on the first console only, but tinit is "armed" to launch a login on any other console on which you press a key. This means that while console 1 is always available, the other consoles aren't used unless you specifically switch to one of them and press a key.

Each virtual console can be running a different foreground application that uses the entire screen. The keyboard is attached to the virtual console that's currently visible. You can switch from one virtual console to another, and thus from one application to another, by entering these keychords:

Use the + (plus) and - (minus) keys in the numeric keypad for these keychords.

You can also jump to a specific console by typing Ctrl-Alt-n, where n is a digit that represents the console number of the virtual console. For instance, to go to /dev/con2 (if available), press Ctrl-Alt-2.

When you terminate the session by typing logout or exit, or by pressing Ctrl-D, the console is once again idle. It doesn't appear when you use any of the cyclical console-switching keychords. The exception is console 1, where the system usually restarts login.

For more information about the console, see devc-con in the Utilities Reference, and "Console devices" in the Character I/O chapter of the System Architecture guide.

Shell

After the character-device driver processes what you type, the command line is passed to a command interpreter or shell.

The default shell is sh, which, under Neutrino, is a link to the Korn shell, ksh. There are other shells available, including small ones that are suitable for embedded systems; see "Shells (command interpreters)" in the Utilities Summary in the Utilities Reference.

In general terms, the shell breaks the command line into tokens, parses them, and invokes the program or programs that you asked for. The specific details depend on the shell that you're using; this section describes what ksh does.

As you type, the Korn shell immediately processes the keys that you use to edit the command line, including completing commands and filenames. When you press Enter the shell processes the command line:

1. The shell breaks the command line into tokens that are delimited by whitespace or by the special characters that the shell processes.
2. As it forms words, the shell builds commands:
   • simple commands, usually programs that you want to run (e.g. less my_file)
   • compound commands, including reserved words, grouping constructs, and function definitions.

   You can also specify multiple commands on the command line.

3. The shell processes aliases recursively.
4. The shell does any required substitutions, including parameters, commands, and filenames.
5. The shell does any redirection.
6. The shell matches the remaining commands, in this order: special builtins; functions; regular builtins; executables.

To override the order in which the shell processes the command line, you use quoting to change the meaning of the special characters.

The sections that follow give the briefest descriptions of these steps -- ksh is a very powerful command interpreter! For more details, see its entry in the Utilities Reference.

Editing the command line

The Korn shell supports emacs-style commands that let you edit the command line:

As in emacs, commands that involve the Ctrl key are keychords; for commands that involve Esc, press and release each key in sequence. For more information, see "emacs interactive input-line editing" in the documentation for ksh.

In order to process these commands, ksh uses the character device in raw mode, but emulates all of the driver's processing of the keys. Other shells, such as esh, use the character device in canonical (edited input) mode.

Command and filename completion

You can reduce the amount of typing you have to do by using command completion and filename completion. To do this, type enough of the command's or file's name to identify it uniquely, then press Esc twice. If possible, the system fills in the rest of the name. For example, if you type appb, then EscEsc, the system completes the command name, appbuilder.

If you prefer to use Tab for completing names, set the shell's complete key binding by typing:

bind '^I'=complete

on the command line or in the ksh profile. For more information about the bind command and the key bindings, see "emacs interactive input-line editing" in the documentation for ksh in the Utilities Reference; for information about the profiles for ksh, see also "Configuring your shell" in Configuring Your Environment.

Reserved words

The Korn shell recognizes these reserved words and symbols:

case   else   function   then    !
do     esac   if         time    [[
done   fi     in         until   {
elif   for    select     while   }

and uses them to build compound commands. For example, you can execute commands in a loop:

for i in *.c; do cp $i $i.bak; done

Entering multiple commands

You can enter more than one command at a time by separating your commands with a semicolon (;). For example, if you want to determine your current working directory, invoke pwd. If you want to see what the directory contains, use ls. You could combine the two commands as follows:

pwd; ls

As described in "Pipes," you can also use pipes (|) to connect commands on the command line.

Aliases

You can define an alias in the shell to create new commands or to specify your favorite options. For example, the -F option to the ls command displays certain characters at the end of the names to indicate that the file is executable, a link, a directory, and so on. If you always want ls to use this option, create an alias:

alias ls='ls -F'

If you ever want to invoke the generic ls command, specify the path to the executable, or put a backslash (\) in front of the command (e.g. \ls).

For information on adding an alias to your profile so that it's always in effect, see "ksh's startup file" in Configuring Your Environment.

Substitutions

The shell lets you use a shorthand notation to include the values of certain things in the command line. The shell does the following substitutions, in this order:

• directories -- tilde expansion
• parameters
• commands
• arithmetical expressions
• braces
• filename generation.

Directories -- tilde expansion

The shell interprets the tilde character (~) as a reference to a user's home directory. The characters between the tilde and the next slash (if any) are interpreted as the name of a user. For example, ~mary/some_file refers to some_file in the home directory of the user named mary.

If you don't specify a user name, it's assumed to be yours, so ~/some_file refers to some_file in your home directory.

Your home directory is defined in your entry in the password database; see the description of /etc/passwd in Managing User Accounts.

Parameters

To include the value of a parameter on the command line, put a dollar sign ($) before the parameter's name. For example, to display the value of your PATH environment variable, type:

echo $PATH

Commands

Sometimes, you might want to execute a command and use the results of the command in another command. You can do it like this:

$(command)

or with the older form, using backquotes:

`command`

For example, to search all of your C files for a given string, type:

grep string $(find . -name "*.c")

The find command searches the given directory (. in this case) and any directories under it for files whose names end in .c. The command substitution causes grep to search for the given string in the files that find produces.

Arithmetical expressions

To specify an arithmetical expression in a command line, specify it as follows:

$(( expression ))

For example:

echo $((5 * 7))

You're restricted to integer arithmetic.

Braces

You can use braces to add a prefix, a suffix, or both to a set of strings, by specifying:

[prefix]{str1,...,strN}[suffix]

where commas (,) separate the strings. For example, my_file.{c,o} expands to my_file.c my_file.o.

Filename generation

Instead of using a command to work on just one file or directory, you can use wildcard characters to operate on many.

Hidden files, i.e. files whose names start with a dot (e.g. .profile), aren't matched unless you specify the dot. For example, * doesn't match .profile, but .* does.

The following examples show you how you can use wildcards with the cp utility to copy groups of files to a directory named /tmp:

Redirecting input and output

Most commands:

• read their input from the standard input stream (stdin, or file descriptor 0), which is normally assigned to your keyboard
• write their output to the standard output file (stdout, or fd 1), which is normally assigned to your display screen
• write any error messages to the standard error stream (stderr, or fd 2), which is also normally assigned to the screen.

Sometimes you want to override this behavior.

For example, the ls command lists the files in a directory. If you want to redirect to output of ls to a file called filelist, enter:

ls > filelist

You can specify a file descriptor for the above redirections. For example, if you don't want to display any error messages, redirect stderr to dev/null (a special file, also known as the bit bucket, that swallows any data written to it and returns end-of-file when read from):

my_command 2> /dev/null

For more information, see "Input/output redirection" in the docs for ksh in the Utilities Reference.

Pipes

You can also use a pipe (|) to to build complex commands from smaller ones:

grep 'some term' *.html | sort -u | wc -l

Programs such as grep, sort, and wc (a utility that counts characters, words, and lines) that read from standard input and write to standard output are called filters.

Quoting special characters

Certain characters may have special meaning to the shell, depending on their context. If you want a command line to include any of the special characters that the shell processes, then you may have to quote these characters to force the shell to treat them as simple characters.

You must quote the following characters to avoid their special interpretation:

| $ ( " ) & ` ; \ ' Tab Newline Space

You might need to quote the following characters, depending on their context within a shell command:

* ? [ # ~ = %

For example, these commands search for all occurrences of the string "QNX Neutrino" in the chapter1.html file:

grep QNX\ Neutrino chapter1.html
grep 'QNX Neutrino' chapter1.html
grep "QNX Neutrino" chapter1.html

However, note that:

grep QNX Neutrino chapter1.html

doesn't do what you might expect, as it attempts to find the string "QNX" in the files named Neutrino and chapter1.html.

Depending on the complexity of a command, you might have to nest the quoting. For example:

find -name "*.html" | xargs grep -l '"QNX.*Neutrino"' | less

This command lists all the HTML files that contain a string consisting of QNX, followed by any characters, followed by Neutrino. The command line uses find to locate all of the files with an extension of html and passes the list of files to the xargs command, which executes the given grep command on each file in turn. All of the output from xargs is then passed to less, which displays the output, one screenful at a time.

This command uses quoting in various ways to control when the special characters are processed, and by which process:

• If you don't put quotes around the *.html, the shell interprets the *, and passes to find the list of files in the current directory with an extension of html. If you quote the *.html, the shell passes the string as-is to find, which then uses it to match all of the files in this directory and below in the filesystem hierarchy with that extension.
• In a similar way, if you don't quote the QNX.*Neutrino string at all, the shell generates a list of files that match the pattern. Quoting it once ("QNX.*Neutrino") works for a single invocation of grep, but this example has the added complexity of the xargs command.
• The xargs command takes a command line as its argument, and the shell interprets this command line for each item that's passed to xargs. If you don't want the QNX.*Neutrino string to be interpreted by the shell at all, you need to put nested quotes around the pattern that you want to pass to grep:

  xargs grep -l '"QNX.*Neutrino"'
    

• The quoting also indicates when you want to execute the less command. As given, the shell passes the output from all of the invocations of xargs to less. In contrast, this command:

  find -name "*.html" | xargs 'grep -l "QNX.*Neutrino" | less'
    

  passes the command:

  grep -l "QNX.*Neutrino" | less
    

  to xargs, which will have quite different results -- if it works at all.

For more information, see "Quoting" in the docs for ksh in the Utilities Reference.

History: recalling commands

The shell lets you recall commands that you've previously entered; use the /\ and \/ (up and down arrows) to move through the history buffer. You can edit the command, if you wish, and then press Enter to reexecute it.

The shell also includes a builtin fc command that you can use to display and edit previous commands, as well as an r alias to fc that reexecutes a previous command. For example:

r string

reexecutes the last command that starts with the given string.

Shell scripts

You can enter shell commands into a text file, called a shell script, and then invoke the commands in batch mode by executing (or shelling) the file. For more information, see the Writing Shell Scripts chapter in this guide.

Utilities

Once the shell has processed all of its special characters, what remains typically consists of commands and the arguments to them. Most commands correspond to executable files somewhere on your system, although some -- such as cd -- are built into the shell.

It's possible for you to have more than one executable file with the same name on your system. The shell uses the PATH environment variable to determine which version to use.

The value of PATH is a list of directories, separated by colons (:), in the order in which you want the shell to search for executables. To see the value of your PATH, type:

echo $PATH

You can put your current directory (.) in your PATH, but it can leave you vulnerable to "Trojan horse" programs. For example, if . is at the beginning of your PATH, the shell looks in the current directory first when trying to find a program. A malicious user could leave a program called ls in a directory as a trap for you to fall into. If you want to have your current directory in your PATH, make sure that you put it after the directories that hold the common utilities.

For information about setting your PATH, see "Environment variables" in Configuring Your Environment.

If you want to know which version of a command the shell will choose, use the which command. For example:

$ which ls
/bin/ls

You can use command-line options to get more information:

$ which -laf ls
-rwxrwxr-x  1 root      root         19272 May 03  2002 /bin/ls

If you try this for a command that's built into the shell, which can't find it:

$ which cd
which: no cd in /bin:/usr/bin:/usr/photon/bin:/opt/bin

The whence command displays what the command means to the shell, including any aliases in effect. For example, if you've created an alias for ls, the output might be:

$ whence ls
'ls -F'

Understanding command syntax

Whenever you look up a command in the Utilities Reference, you'll see a syntax statement that summarizes how you can use the command. For most commands, this statement consists of:

command_name

The name of the command to be executed. This may be the name of an executable program, such as a utility, or it may be the name of a command built into the shell.

options

The specific behavior that you want to invoke for the command. Options typically consist of an alphanumeric character preceded by a hyphen (e.g. -c). Some options take an argument (e.g. -n number). If you specify an option that takes an argument, you must include its argument as well.

operands

Data the command requires (e.g. a filename). If a command lets you enter multiple operands, they're usually processed in the order you list them. Unlike options, operands aren't preceded by a hyphen (e.g. more my_file).

The entries in the Utilities Reference use some special symbols to express the command syntax:

...

You can specify one or more instances of the previous element. For example, in the more utility syntax, the ellipsis after the operand file indicates that you can specify more than one file on the command line:

more myfile1 myfile2
  

[ ]

The enclosed item is optional.

|

You can use only one of the items (e.g. -a|-f).

You don't actually type these symbols when you invoke the command. For instance, the syntax description for more, is given as follows:

more [-ceisu] [-n number] [-p pattern]
     [-/ pattern] [-t tag] [-x tabstop] [file...]

You can combine multiple options that don't take an argument. The -ceisu notation is shorthand for -c -e -i -s -u.

If an argument to a command starts with a hyphen, you can signal the end of the options by using a double hyphen:

ls -l -- -my_file

For more information, see Utility Conventions in the Utilities Reference.

Displaying online usage messages

If you want a detailed description of a utility, see the Utilities Reference. But if you just want a quick reminder of the syntax and options, you can display the utility's online usage message by invoking the use command (it's similar to man in UNIX and Linux). For example, to display the message for more, type:

use more

If you request usage for a command, and the command either doesn't have an executable in the current path or doesn't contain usage message records, use displays an error message. For more information, see use in the Utilities Reference -- or simply type use use.

Executing commands on another node or tty

If the machines on your network are running Qnet (see Using Qnet for Transparent Distributed Processing), you can execute commands on another machine. This is known as remote execution. For example:

on -n /net/dasher date

where /net/dasher is the name of the node that you want to run the command on.

When you invoke a command on another node, the command's standard input, standard output, and standard error output are displayed on your console screen (or terminal) unless you explicitly redirect them to another device.

To run a command on a specific tty, use the -t option, specifying the terminal name. For example:

on -t con3 login root

For more information, see the on command in the Utilities Reference.

Priorities

By default, when you start a utility or other program, it runs at the same priority as its parent. (Actually, priorities aren't associated with a process, but with the process's threads.) You can determine the priority of a process's threads by looking at the output of the pidin (Process ID INformation) command.

If you want to run something at a specific priority, use on, specifying the -p option. If you want to specify a relative priority, use the nice command.

Basic commands

Here are some Neutrino commands that you'll frequently use:

For more information about these and other commands, see the Utilities Reference; its Utilities Summary arranges all the utilities according to what you use them for.

International keyboards

If you're using Photon, you can use phlocale to change the keyboard mapping (among other things). The choices are in /usr/photon/keyboard, and include mappings for specific languages (e.g German, French), as well as for several versions of the Dvorak keyboard layout (a layout that some people consider more efficient than the standard QWERTY one).

If we don't supply the mapping you need, you can use the mkkbd utility to create your own.

Some keyboard layouts (e.g. for the French and German languages) use accent keys which, by themselves, don't generate a character. Neutrino treats these keys as "dead" keys. Pressing a dead key, followed by a second key, modifies the second key, creating an accented character. For example, to create a Ü character if you're using the French keyboard layout, press Shift-[ followed by Shift-U.

You can also generate composed characters by pressing and releasing Alt followed by two keys or keychords. For example, if you're using the US English layout, you can press and release Alt, followed by Shift-", and then Shift-U, to get a Ü character.

Neutrino for MS-DOS users

If you're familiar with Microsoft Windows, you might need to know about the Neutrino equivalents for the basic DOS commands and variables.

DOS commands and their Neutrino equivalents

The following table lists the Neutrino equivalents of some common MS-DOS commands. For more information about the Neutrino commands, see the Utilities Reference.

diskcomp

These steps are the Neutrino equivalent to the DOS diskcomp command:

1. Copy the master disk to a file:

   cp /dev/fd0 referencecopy
     

2. Compare other disks with the copy of the master file:

   cmp referencecopy /dev/fd0
     

3. Copy the master file to a new floppy:

   cp referencecopy /dev/fd0
     

MS-DOS local command-interpreter variables

The following table lists some builtin MS-DOS local command-interpreter variables and their equivalent Neutrino environment variables or commands:

Troubleshooting

Here are some common problems you might encounter while working on the command line:

Why can't I run my program called test?

The shell has a builtin command called test. When the shell parses the command line, it matches any builtin commands before it looks for executable files.

You have two choices: rename your program, or specify the path to it (e.g. ./test).

Why do I get a "not found" message when I try to run my program?

The program is likely in a directory that isn't listed in your PATH. In particular, your current directory isn't in your PATH for security reasons.

Either add the executable's directory to your PATH or specify the path to the command (e.g. ./my_program). For more information, see "Utilities," earlier in this chapter.

Why does root have access to different commands?

The root user has a different PATH setting that includes such directories as /sbin and /usr/sbin. These directories contain executables and managers that (typically) only root can use.

If you aren't logged in as root, you can still run some of the utilities in /sbin if you have the right permission, but you'll have to specify the full path (e.g. /sbin/logger) or add the directory to your PATH.

When I list a directory, I don't see files that start with a dot.

Files whose names start with a dot (.) are called hidden files. To list them, use the -a option to ls.

Why am I getting a "No such file or directory" message?

The shell can't find the file or directory that you specified. Here are some things to check:

• Have you typed the name correctly? In Neutrino, the names of files and directories are case-sensitive.
• Does the name contain spaces or other special characters?

  If you have a file called my file and you don't escape the meaning of the space, the shell uses the space when breaking the command line into tokens, so the command looks for one file called my and another called file.

  Use quoting to escape the meaning of the special characters (e.g. less "my file" or less my\ file). For information about the other characters that you need to quote, see "Quoting special characters."

How do I work with a file whose name starts with a hyphen?

Neutrino utilities use the hyphen (-) to denote an option (e.g. head -n 10 some_file). If you create a file whose name starts with a hyphen, and you pass that filename as an argument to a utility, the utility parses the filename as one or more options.

Most utilities recognize a double hyphen (--) to mean "end of options." Put this before your filename:

head -- -my_file
  

For more information, see the Utility Conventions chapter in the Utilities Reference.

Why do I get a "Unrecognized TERM type" message when I start programs such as vi?

Either your TERM environment variable isn't set correctly, or there isn't an entry for your terminal type in /usr/lib/terminfo/ (or possibly /etc/termcap); see "Terminal support," earlier in this chapter.