|This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.|
Photon Terminal window
pterm [-ABbcEGLlnPpQqrTUvXZz] [-a font][-C path] [-D fd] [-d path] [-F n] [-f font ] [-g RxC] [-H N] [-h height[%]] [-K colors] [-M RxC] [-m RxC] [-N fd] [-R prefix] [-S i|m|n] [-s server] [-T] [-t string] [-u opts] [-w width[%]] [-x position[%] [r]] [-y position[%][r]] [program [argument...]]
The default values listed below are the ones coded in the pterm application; they might be overridden by a configuration file.
- Pass all Alt key combinations to the device.
- -a font
- Add font to the font list.
- Cursor always blinks (default: cursor blinks only when window has focus).
- Cursor never blinks.
- -C path
- Use this configuration file.
- Disable the Terminal Properties dialog.
- -D fd
- Attach to the given file descriptor instead of using a pty.
- -d path
- Open given device instead of using a pty.
- Don't modify environment variables (default: unset LINES and COLUMNS; set TERM according to the protocol).
- -F n
- Use the n-th font from list (starting from 0).
- -f font
- Use font as the current font.
- Pass signals to the program.
- -g RxC
- Set the initial size to R rows, C columns.
- -H N
- Save up to N lines in the scroll-back buffer.
- -h height[%]
- The height of the window, in pixels, or as a percentage of the screen height if % is specified.
- -K colors
- Specify the foreground and background colors.
The colors argument is one or two numbers in the range 0 to 7; the
first is for the foreground and the second for the background.
The numbers are indexes into the first 8 entries in the palette for
pterm (see the
"Files" section, below).
For example, this command sets the initial colors to black (0) on white (7):
pterm -K 07
- Don't create a new session.
- ("el") Start the shell as a login shell.
- -M RxC
- Set maximum size to R rows, C columns.
- -m RxC
- Set minimum size to R rows, C columns.
- -N fd
- Output device name to this fd.
- Don't read the configuration file.
- Increase program's priority (default: don't change any priority).
- Decrease priority.
- Use QNX protocol (default: ANSI).
- Never confirm before closing.
- -R prefix
- Use prefix for the pty (default: /dev).
- Display a scrollbar.
- The initial state of the main window (iconified, maximized, or normal).
- -s server_name
- The name of the Photon server:
If server_name is: This server is used: node_path node_path/dev/photon fullpath fullpath relative_path /dev/relative_path
- Disable text-mode mouse.
- -t string
- Set window title to string.
- Don't realize the pterm window until it receives output. This option takes precedent over -z and -Z.
- -u opts
- Unset given options (AaBbQv) even if set in the configuration file.
- Visual bell (default: use audio beep only).
- -w width[%]
- The width of the window, in pixels, or as a percentage of the screen width if % is specified.
- Exit with shell's exit status (default: always exit with zero).
- -x position[%][r]
- The x coordinate of the upper-left corner of the window, in pixels, or as a percentage of screen width if % is specified. If r is specified, the coordinate is relative to the current console.
- -y position[%][r]
- The y coordinate of the upper-left corner of the window, in pixels, or as a percentage of screen height if % is specified. If r is specified, the coordinate is relative to the current console.
- Wait until closed unless exit status is zero (default: close window as soon as the command terminates).
- Wait until closed explicitly.
- program [argument...]
- Name of the program that pterm starts. A shell is started if neither program nor any of the following options are specified: -D fd, -d path, or -N fd.
The pterm application is a terminal emulator that opens a window on the Photon workspace and attaches itself to a character device. The device is usually a pty (pseudo-tty) on the local node, but you can use the -R option to override the node (e.g. if the pty driver isn't running on the local node). Or you can use the -D or -d options to specify a device (e.g. a serial link connected to a modem).
By default, pterm starts a shell on the "slave" side of the pty. The shell won't be spawned if a -D or -d option is used to override the device or if a -N option is used, in which case it outputs the device name to the given file descriptor. In all cases, you can use a command-line argument to force a program to be started on the device.
|If the -d option specifies a pty, then the program is started on the specified device and the other side of the pty remains unused (which is probably not the desired behavior).|
Before spawning the command, pterm sets the TERM environment variable to a value depending on the chosen terminal emulation. It'll be one of the following:
You can use the -E option to pass the original environment to the command.
By default, pterm closes its window as soon as the program spawned in it terminates. The -Z or -z option overrides this default -- the window remains open until the user closes it. This option can be useful when a program is spawned that outputs a message and then exits immediately.
The -G and -X options can also be useful for a program or script that calls pterm.
If -G is used, then whenever pterm catches a signal other than SIGTERM, SIGCHLD, SIGILL, SIGWINCH or SIGSEGV, the signal is passed to the spawned command. This means that a script can spawn pterm and easily kill its command with a chosen signal.
The -X option causes pterm to exit with the same exit status that the command returned (or even to kill itself with the signal that killed the command).
If the user closes the window while the command is still running, or if pterm catches a signal and either the -G option wasn't specified or it is the SIGTERM signal (which can mean that either Photon is being closed or pterm is being killed using the slay command), pterm:
- Sends the SIGHUP signal to the command.
- If the command survives, sends the SIGTERM signal.
If the -X option was specified and the command survives both signals, pterm terminates with exit code 1.
If a process running on the pterm's device is producing output very quickly, you can increase the total throughput by running the "consumer" at a priority lower than the "producer." Data then arrives at the pterm in larger portions. You can further increase the throughput by using larger buffers in the pty driver -- pterm uses a 4K buffer, while the pty driver's default is 512 bytes.
You can use the -P or -p option either to reduce pterm's priority or increase the spawned command's priority. Of course, changing the priority has other side effects: if pterm's priority is reduced below the default (-p option), then other processes running at the default priority may significantly reduce the speed of pterm and, as a result, the total throughput. On the other hand, if the process in pterm is running at an increased priority (-P option), then it may affect the performance of other processes, especially when it doesn't produce much output.
You can use these rudimentary clipboard keys:
|If you want to:||Press:|
|Allow text-mode applications to receive mouse events.||Ctrl-Alt-T|
|Copy selection to the clipboard.||Ctrl-Alt-X or Ctrl-Alt-Del|
|Don't allow text-mode applications to receive mouse events.||Ctrl-Alt-S|
|Paste contents of clipboard to the current cursor location.||Ctrl-Alt-V or Ctrl-Alt-Ins|
|Paste directly from the selection without using the clipboard.||Ctrl-Alt-P|
|Select the word under the cursor or to the left of the cursor.||Ctrl-Alt-W|
|Select the word under the cursor or to the left of the cursor and search for that word in Helpviewer.||Ctrl-Alt-H|
|Select/Unselect current selection.||Ctrl-Alt-R|
The mouse supports the following user activities within pterm:
|If you want to:||Press:|
|Copy selection to the clipboard.||Right-click or Right-drag (selecting)|
|Paste the contents of the clipboard to the current cursor location.||Ctrl-Right button|
|Paste from the clipboard.||Middle button|
|Paste selection to the current cursor location.||Shift-Right button|
|Pop up a menu.||Alt-Right button|
|Pop up a menu (if mouse in text mode is disabled).||Right button|
|Select a block.||Ctrl-Left button|
|Select a block (if mouse in text mode is disabled).||Left button|
|Select a "stream."||Shift-Left button|
|Select a word (C identifier).||Alt-Left button, or double-click on the word|
|Select the current line||Triple-click on the line|
|Select the entire screen||Quadruple-click on the screen|
Several keychords are recognized by pterm:
|If you want to:||Press:|
|Change font||Ctrl-Alt-[ or|
|Invoke the Terminal Properties dialog.||Ctrl-Alt-C|
|Move through the scrollback buffer.||Ctrl-Alt and /\, \/, Home, End, Pg Up, or Pg Dn|
The Ctrl-Alt-[ and Ctrl-Alt-] keychords change the font to the previous/next on the list, without changing the terminal size (rows and columns).
Ctrl-Alt-< and Ctrl-Alt-> change the font without changing the window dimensions (measured in pixels). If, however, the new terminal size would be smaller than the minimal size, then the window must be grown. If the new size would be larger than the maximum size, the window won't be made smaller -- instead, the terminal's margins are adjusted to fill the window.
You can store certain visible aspects of the terminal in a configuration file (see the "Files" section) and modify them by using the Terminal Properties dialog invoked by Ctrl-Alt-C:
- Window Title area
- Here you can change the title or restore the default title. If you
don't remember the escape sequences you can use in the title, press
the button marked ? to see the list.
The window title can contain special escape sequences:
Escape Meaning %% A single % character %$ PID of the current process %0 Just the argv argument of the current process executing in the window %A Arguments of the current process executing in the window starting at the argv position %a Arguments of the current process executing in the window starting at the argv position %d Device name (e.g. ttyp1) %N Filename of the current process executing in the window %P Pathname of the current process executing in the window %p Device path (e.g. /dev/ttyp1) %T Current time %u User's login name
- Window Size area
- Here you can set the current terminal's size, as well as the minimum and maximum size (measured in pixels).
- Font area
- You can choose from one of the predetermined font styles and sizes, or you can select the custom font list. You edit the custom font list by clicking Customize... For more information see the section, Customizing your font list.
- Terminal Preferences area
- You can choose:
- Cursor blinking (equivalent to the -B and -b options)
- Whether the "general" or "command-specific" configuration file is saved when you click the Save & Close button.
- Visual bell (equivalent to the -v option)
- To suppress the Window Manager's Alt-key combinations and pass them to the device instead (equivalent to the -A option)
- To display a scrollbar on the pterm window.
- The number of lines in the scroll-back buffer (equivalent to the -H option).
Here you choose the required font for your custom font list:
All the fonts displayed in this dialog must have the same character encoding. By default, pterm assumes it's the PC character set ("IBM code page 437"). If your fonts use a different character encoding, you'll have to specify a charsets file (click "Browse...") that defines that encoding. See ptermcs for information on creating charset files.
Run pterm using the Photon server on node my_node:
Run pterm at initial position (10,10) with initial dimension of 200*300:
pterm -x10 -y10 -h200 -w300
When pterm is started, it looks for your local configuration file-- if that file doesn't exist, a global configuration file is loaded. Whenever you click Save & Close in the Terminal Properties dialog, the local file is saved. The configuration files have the following pathnames:
where $0 is the name used for invoking pterm -- usually it's pterm; if $PHOTON_PATH is unset or empty, /usr/photon is used instead.
- If the -C option is given, the option's argument is used.
- Otherwise, if $PTERMRC is non-empty, its value is used.
- Otherwise, if $HOME/.ph/pterm/$0. $CMD.rc exists, it's used (where $CMD is the command-specific file started in pterm).
- Otherwise, $HOME/.ph/pterm/$0.rc is used.
You can use the -n option to suppress the loading of the current settings from the configuration files. The -c option disables the Terminal Properties dialog.
You can use the -u option to restore the default behavior of the following options: AaBbQv. This option overrides the setup in the configuration file.
- Use Alt key combinations for window manager commands.
- Suppress loading of font table from configuration file.
- Clear always-blink option for cursor.
- Clear never-blink option for cursor.
- Use the ANSI protocol.
- Turn off the visual bell.
You can give several option characters to the -u option at one time (e.g.-uabQv). The -ub and -uB options mean the same thing. The always-blink (-B) and the never-blink (-b) options are two states of a three-state switch. The third state (activated with either -uB or -ub) is "Blink when pterm has focus."
When pterm is started, it searches for a palette file:
- If the PTERMPAL environment variable is defined, its value is assumed to be the path to a palette file.
- Otherwise, pterm looks for $HOME/.ph/pterm/pterm.pal or $PHOTON_PATH/pterm.pal.
The palette file can be either a binary file containing sixteen 32-bit entries or a text file containing sixteen 8-digit hexadecimal numbers separated by newlines (and terminated with a single newline). If the length of the file is neither 64 nor 144 bytes, the file is assumed invalid.
The palette file is capable of displaying 16 colors: 8 "normal" colors and 8 "bright" colors in the same way that a standard CGA/VGA does. Color numbers are indexes into this array. The default array has 16 elements corresponding to 16 standard CGA colors:
|7||WHITE (light grey)|
|8||BRIGHT BLACK (dark grey)|
|14||BRIGHT BROWN (yellow)|
- The name of the root directory containing Photon files.
- The path to the palette file.
- The name of a local configuration file.
- Set, depending on the chosen terminal emulation, to one of: