Chapter 9.0 X Windows Continues...

Back to Sections 9.2.2 through
9.2.3 The X Server Program X Server Start Up Options Mouse Button Mapping Keyboard Mapping Server Error Logging X Server Performance Tuning Guide The Default Font Path
9.2.4 X Display Management Under CodeBuilder
9.3 CodeBuilder X Window Software Overview
9.3.1 Preparing Your Macintosh Control Panels
9.3.2 Getting Started With X
9.3.3 Building X Applications Running X Client Applications The X11 Application Development Environment Under CodeBuilder Programming Notes
9.4 X Window Software Frequently Asked Questions

9.2.3 The X Server Program

When the X server starts up, it takes over the display, except for the Macintosh menu bar running horizontally along the top of the display. Use the menu bar to suspend the X server to access the CodeBuilder terminal window environment or other running Macintosh applications.

The X server program is the file /usr/X11/bin/X11/XMachTen or by its linked name, /usr/X11/bin/X. By default, xinit(n) will automatically run /usr/X11/bin/X.

You are prevented from running the X server program except by way of xinit under CodeBuilder. X Server Start Up Options

By default, xinit will automatically run /usr/X11/bin/X. If you need to start the X server with options, create a file named .Xparams in your home directory. This file should contain any option flags you wish to pass to the server. If you require more extensive customization, create a file named .xserverrc in your home directory and xinit will execute this file as a shell script. Start up options alter the default X server behavior and are useful for three button mouse operation, font path redirection, and menubar configuration among other things.

A sample Xparams file is available in /usr/X11/lib/X11/xinit/Xparams. Copy this file to your home directory as .Xparams if and only if you want to start the server with different options. If no .Xparams file is found, the X server uses the default options in /usr/X11/lib/X11/xinit/Xparams.

The following command line options for the X server may be useful on a CodeBuilder system:

-auth authorization-file
Specifies a file which contains a collection of authorization records used to authenticate access. See also the xdm and Xsecurity manual pages.
Disables certain kinds of error checking, for bug compatibility with previous releases (e.g., to work around bugs in R2 and R3 xterms and toolkits).
Disables backing store support on all screens.
-co filename
Sets name of RGB color database.
-dpi resolution
Sets the resolution of the screen, in dots per inch. To be used when the server cannot determine the screen size from the hardware.
-fc cursorFont
Sets the default cursor font.
-fn font
Sets the default font.
-fp fontPath
Sets the search path for fonts. This path is a comma separated list of directories which the X server searches for font databases.
Starts the server in full screen mode. In this mode, the Macintosh menu bar is hidden by the X desktop. Pull-down menus from the Macintosh menu bar remain accessible by pressing the mouse button while dragging the cursor along the top edge of the desktop.

This option may not work on PCI Macintosh systems.
Prints a usage message.
Causes all remaining command line arguments to be ignored.
-ld kilobytes
Sets the data space limit of the server to the specified number of kilobytes. A value of zero makes the data size as large as possible. The default value of -1 leaves the data space limit unchanged.
-ls kilobytes
Sets the stack space limit of the server to the specified number of kilobytes. A value of zero makes the stack size as large as possible. The default value of -1 leaves the stack space limit unchanged.
-mbm middle-key
Changes the middle mouse button keystroke mapping. The key entered as a decimal value representing the Macintosh virtual key code corresponding to the desired key. Allowable values are between 0 and 127. Refer to section " Mouse Button Mapping" for a table of keys and virtual key codes.
-mbr right-key
Changes the right mouse button keystroke mapping.
Starts the server in dedicated full screen mode. In this mode, the Macintosh menu bar is hidden by the X desktop and access to Macintosh pull-down menus is completely disabled.

The xtmenu(n) program, run from your X window manager menu environment, may be used to temporarily restore access to your Macintosh desktop. Caution: this option locks out access to Finder and other running Macintosh applications!
Specifies that the Macintosh Option key will be used in combination with the mouse button keystroke to simulate the middle or right mouse button. When used without the -mbm or -mbr start up options, the default middle and right mouse button keystrokes become <Option-left arrow> and <Option-right arrow>, respectively. Selecting this option causes all arrow keys, including the Up and Down arrows, to function normally.
Runs the server in StaticColor mode, preventing X client modification of the Macintosh color table.
Disables save under support on all screens.
-to seconds
Sets the default connection time-out in seconds.
Forces the default backing-store of all windows to be WhenMapped; an easy way of getting backing-store to apply to all windows. This option can be useful when displaying X applications over slow serial links. Mouse Button Mapping

Many X clients assume the mouse has three buttons. The X server simulates the middle and right mouse buttons with keystrokes - by default the left-arrow key generates middle button events and the right-arrow key generates right button events - the real mouse button generates left button events. The open-Apple or Command key is the Meta (or when shifted, the Alt) modifier; Meta can also be obtained by pressing the up-arrow key. The down-arrow key duplicates the Control key. Meta, Control and Shift are often used in combination with other keystrokes or mouse clicks. For example, the terminal emulator xterm pops up menus in response to Control-middle and Control-right.

The original function of the arrow keys may be obtained by holding down the Option key while pressing one of the arrow keys. Normal arrow key functions are also restored when you re-map the middle and right mouse buttons using the -mbm and -mbr server start up options or when you configure the server to accept the <Option-mouse key> combination using the -mo start up option.

Three Button Mouse Configuration. Several commercial three button mice are offered for the Macintosh. All operate by assigning an unused keyboard key or key combination to the middle and right mouse buttons. The X server supports the reconfiguration of the mouse keys from the default left-arrow and right-arrow to any other keyboard key or <Option-key> combination. By matching the X server mouse button configuration with your three button mouse hardware configuration, you can shift your X three button operation entirely to the hardware mouse.

The default keystrokes for the middle and right mouse buttons may be changed via the -mbm and -mbr server start up parameters, described in the previous section. The values to assign to the options for a given Macintosh key are as follows:

Page up
Page up
Page down
Left arrow
Right arrow
Down arrow
Up arrow



The X server may also be configured to accept the Macintosh Option key in combination with the selected button keystroke using the -mo start up parameter described in the previous section. This allows keyboard keys to function both as normal keys and, when the Option key is pressed, as mouse buttons.

If the default mouse button configuration is modified or you use the Macintosh Option key in combination with another key to simulate a mouse button, all arrow keys revert to their original functions.

Example Three Button Mouse Configuration. Suppose you own a Logitech Mouse and would like to map the middle and right mouse buttons to the <Option-F14> and <Option-F15> key combinations when running the CodeBuilder X server. Your Logitech MouseMan Control Panel would look something like this:

Figure 35. Logitech MouseMan Control Panel

The .Xparams configuration file in your home directory would look like this:
-mo -mbm 107 -mbr 113 -cmdkey meta Keyboard Mapping

The default layout for keyboard keys in the X server corresponds to the U.S. character set under Mac OS. Special characters and symbols, including characters with diacritical marks, are available by pressing the Option key in combination with certain letter and number keys. Refer to the Macintosh User's Guide for more information on typing special characters.

Configuring International Keyboard Layouts. Your Keyboard control panel indicates the keyboard layout in force for your Macintosh. If your keyboard layout is an international (non-U.S) layout, the default U.S. X key layout must be re-mapped when the X server is launched to match your country's layout.

The xmodmap(n) program is used to re-map the default U.S. character set within the X server for use in other countries. Xmodmap is run by the .xinitrc script when the X server starts up. The script searches for a key mapping file called .Xmodmap in the directory /usr/X11/lib/X11/xinit. If found, xmodmap configures the X server using the contents of the mapping file.

Mapping files are named Xmodmap-XX where XX represents the country code for the desired keyboard layout:

Great Britain
French Canadian

To change the X default U.S. keyboard layout, enter the following from a CodeBuilder terminal window prior to starting the X server for the first time:

ln /usr/lib/X11/xinit/Xmodmap-XX/usr/lib/X11/xinit/Xmodmap
This command creates an Xmodmap link file to your country's X key map. The Xmodmap file will be read into the server by xmodmap each time the server starts up via the xinitrc file. To restore the X key map to the default U.S layout, delete the link file and restart the X server.

For international X keyboard map files not listed above, contact technical support at Tenon Intersystems.

X Meta and Alt Keys. Under the CodeBuilder X Server, hot key operation (using the Apple Command key) normally associated with a CodeBuilder terminal window is disabled. The Command key functions as an X Meta (or when shifted, Alt) key when the X server is the front window. Many applications, including the OpenLook Virtual Window Manager, use the Meta and Alt keys as keyboard modifiers.

Apple reserves certain keystroke combinations for special effects. All Command-Shift-number sequences are not delivered to the X server and are unavailable for use by your X applications.

The Macintosh Option key is not available for use as a Meta key. Server Error Logging

The X server logs cumulative error messages to the file /var/adm/X0msgs. If you are having trouble starting the X server, or if the server suddenly exits, the contents of this file may contain helpful troubleshooting information.

If the X0msgs file does not exist, the X server will create a new one when it starts up.

You may optionally remove the X0msgs file and create a symbolic link to your console terminal:
ln /dev/console /var/adm/X0msgs
With the symbolic link in place, errors logged by the X server will appear in the CodeBuilder console window. X Server Performance Tuning Guide

The following tips will help you optimize the performance of the CodeBuilder X Server. The Default Font Path

X fonts are stored locally as individual files in directories. The list of directories and font servers an individual X server uses when trying to open a font is controlled by the font path.

The default font path for the X server contains four directories:

This directory contains many miscellaneous bitmap fonts that are useful on all systems. It contains a family of fixed-width fonts, several Kana fonts from Sony Corporation, two JIS Kanji fonts, two Hangul fonts from Daewoo Electronics, two Hebrew fonts, the standard cursor font, two cursor fonts from Digital Equipment Corporation, and cursor and glyph fonts from Sun Microsystems. It also has various font name aliases for the fonts, including fixed and variable.
This directory contains outline fonts for Bitstream, Inc.'s Speedo rasterizer. A single font face, in normal, bold, italic, and bold italic, is provided.
This directory contains bitmap fonts contributed by Adobe Systems, Inc., Digital Equipment Corporation, Bitstream, Inc., Bigelow and Holmes, and Sun Microsystems, Inc. for 75 dots per inch displays. An integrated selection of sizes, styles, and weights are provided for each family.
This directory contains 100 dots per inch versions of some of the fonts in the 75dpi directory.

Font databases are created by running the mkfontdir(n) program in the directory containing the compiled versions of the fonts (the .pcf files). Whenever fonts are added to a directory, mkfontdir should be rerun so that the server can find the new fonts. If mkfontdir is not run, the server will not be able to find any fonts in the directory.

9.2.4 X Display Management Under CodeBuilder

The xdm(n) program manages a collection of X displays, which may only be on the local host with CodeBuilder. The design of xdm was guided by the needs of X terminals as well as the X Consortium standard XDMCP, the X Display Manager Control Protocol. Xdm provides services similar to those provided by init(1), getty(1) and login(1) on character terminals: prompting for login name and password, authenticating the user, and running a session. When your CodeBuilder system is configured to run the X server with xdm, your users will be presented with a friendly, uniform entry into the X Window system. Xdm has many configuration options which are described in detail in the online xdm manual page. This section will concentrate on configuring CodeBuilder and the X server to be controlled by xdm.

9.3 CodeBuilder X Window Software Overview

This release of the CodeBuilder X Window Software is based on the public release of X11, release 6, from MIT. Its purpose is to provide the necessary tools to allow for the development and display of X applications under CodeBuilder on a Macintosh. To that end, the release contains an X Window server, fonts, a font server, programming libraries, configuration files, and documentation from the X11 R6 release adapted for use under CodeBuilder. Programming and server environments in the OpenLook GUI style, based on Sun Open Look 3.1, are included. The release also includes a suite of public X client applications in source form as a reference aid in program development.

The main display server components provided are:

The CodeBuilder X Window Server
The OpenLook Window Manager and user environment
X11 fonts in Portable Compiled Format and a network font server

The main client development and run-time library components provided are:

The X11 library containing the core of the X protocol
The X Intrinsics toolkit library
The Athena Widget set of buttons, pull-down menus, labels, etc.
The X Miscellaneous Utility used by the Athena widget set
The library supporting a security authorization for client/server connections
The library supporting the Shape, Multi-buffering and MIT-misc. extensions
The library of the Input extension to the protocol supporting alternative input devices
The Xview widget library
The OpenLook graphics library
The Application Protocol Interface library supporting the creation of PEX protocol, version 5.1
The Xlib-level C interface library to the PEX protocol, version 5.1
The library of X Display Manager Control Protocol routines
The configuration system for generating Makefiles
A source distribution of MIT client and demonstration programs

The software in this release is contained on CD-ROM. When installed, the X11 software will reside in the following directories after the installation:

X11 library archive files (libX*.a)
X11 configuration files, fonts and application default resource files
X11 executable files
X11 include files for application development
X11 manual pages
include files for OpenLook application development

9.3.1 Preparing Your Macintosh Control Panels

When launched, the X server will configure itself based on the settings in the Monitors, Sound, Mouse, and Keyboard Control Panels. The X server's performance characteristics can be tuned in the CodeBuilder Controls control panel.

You must visit the Monitors control panel prior to running the X server. Open your Monitors control panel and select anything but the 4 or 16 Colors or Grays setting.

Figure 36. The Monitors Control Panel

In a multi-screen or video mirroring configuration, the X server runs on the main screen (the screen containing the menu bar).

You are prevented from changing the monitor characteristics while the X server is running. Doing so will cause the X server to exit abruptly.

Open your Mouse control panel and review your mouse tracking and double-click rate. The X server obeys the settings in this control panel and ignores requests from X clients to change mouse characteristics.

Figure 37. The Mouse Control Panel

Open your Keyboard control panel and review your keyboard repeat rate and delay, if any. The X server obeys the settings in this control panel and ignores requests from X clients to change keyboard repeat frequency.

Figure 38. The Keyboard Control Panel

Open your Sound control panel and review the sound and intensity. X clients that ring the system bell will generate the selected sound. The X server will also honor X client requests to change bell duration and to turn on or off the bell. These requests will not affect your Sound control panel settings.

If you have a Control Strip control panel, select the Hide Control Strip option when running the X server.

Figure 39. The Control Strip Control Panel

Open your CodeBuilder Controls control panel. When the Scheduling Priority slide bar is moved upward toward the CB mark, the X server will draw output faster to the screen. When the slide bar is moved downward toward the Mac mark, keyboard input and window manipulation (re-positioning, re-sizing, etc.) response will be quicker. The recommended slide bar setting that optimizes these potentially competing demands on the X server is shown below.

Always close the CodeBuilder Controls control panel to activate the slide bar settings.

Figure 40. The CodeBuilder Control Panel

9.3.2 Getting Started With X

Following is a road map for information on starting, customizing, operating, and maintaining the X Server.

9.3.3 Building X Applications

Most of the distributed X client executable files in the /usr/X11/bin directory have been created from the source files in /base/src/X11/R6. This section discusses the general procedure for creating X client applications under CodeBuilder.

The Makefile in X client software is generated automatically by the imake program. The program combines machine-independent descriptions (called Imakefiles) of targets to be built with machine-dependent sets of parameters. The xmkmf(n) script in /usr/X11/bin/ invokes imake to build the Makefile from an Imakefile.
  1. First, you must create a working area for X11 development:
mkdir /base/macppc/X11
cd /base/macppc/X11
lndir /base/src/X11
  1. To build a single X client, e.g. xlogo, make the Makefile and executable:
cd /base/macppc/src/X11/R6/mit/clients/xlogo
  1. To install the application(s) in /usr/X11/bin/ type:
make install
  1. To install the application manual page(s) in /usr/X11/man/mann type:
  1. If you chose to install the client(s), you may free up disk space by deleting the extra copy of the executable image(s):
make clean
To build the entire X client suite, follow these additional steps:
  1. Make the master Makefile using the xmkmf utility:
cd /base/macppc/X11/R6/mit/clients
  1. Build the application Makefiles and executables:
make Makefiles
then follow steps 3 through 5, above.
Compiler warning messages are expected from some clients in the MIT distribution. These warnings will not adversely affect the client's operation under CodeBuilder. Running X Client Applications

The build process may be tested by executing an application program compiled and installed in the previous step and instructing it to display on the local X server. Online manual pages are available for each of the X client applications.

Make sure the X server is running (refer to the previous section). Start the client:
/usr/X11/bin/xlogo & The X11 Application Development Environment Under CodeBuilder

The imake configuration utility is included to generate machine-specific Makefiles from machine-independent Imakefiles. Another utility, called makedepend, is provided to generate Makefile dependencies for C language files. The xmkmf shell script in /usr/X11/bin/ is used to create Makefiles from Imakefiles. The easiest way to construct an Imakefile is to start with one that does something similar and modify it. The various macros that are used in an Imakefile are defined in the file /usr/X11/lib/X11/config/Imake.rules. Examples of Imakefiles can be found under the /base/src/X11/R6/mit/clients directory. You are strongly urged to use imake and makedepend so that your software will work across releases.

The configuration files for imake are located in the directory /usr/X11/lib/X11/config/. Makefiles are created from a template file named Imake.tmpl, a machine-specific .cf file, and a site-specific site.def file. The template file should not be modified.

The file defines the specific configuration for application development under CodeBuilder and need not be modified.

The following suggestions are offered by the MIT X Consortium on writing X applications that are portable to other hardware platforms:
  1. Keep all source file names to 12 characters or less. This is the maximum number of characters that older System V file systems allow when using a source code control system.

  2. If you absolutely must use Makefiles instead of Imakefiles, link against -lX11 instead of -lX. If you are using imake, use the symbolic names $(XAWLIB), $(XMULIB), $(XTOOLLIB), $(EXTENSIONLIB), and $(XLIB). Xaw clients may use the symbol XawClientLibs to refer to the appropriate libraries.

  3. Include header files using the syntax <X11/file.h> instead of X11/file.h, <X/file.h>, or X/file.h.

  4. Include <X11/Xos.h> if you need types.h, string.h or strings.h (then use the routines index and rindex instead of strchr and strrchr), file.h, time.h, or unistd.h.

  5. If you need to put in System V vs. BSD dependencies, use #ifdef SYSV. If you need SVR3 vs. SVR2, use #ifdef USG.

  6. Do not assume that the root window's Visual (returned by the DefaultVisual macro) is the only one available. Some color screens may use a black and white window for the root or could provide StaticColor as well as PseudoColor visuals. Unfortunately, most libraries do not have adequate support for locating visuals to use. In the meantime, use XGetVisualInfo().

  7. Use -display displayname to specify the X server to contact. Do not simply assume that a command line argument that has a colon in it is a displayname. If you accept command line abbreviations, make sure that you also accept the full -display.

  8. Use -geometry geomspec to specify window geometry. Do not simply assume that command line argument that begins with an equal sign is a window geometry. If you accept command line abbreviations, make sure that you also accept the full -geometry.

  9. Use the .man suffix for program manual page sources. Programming Notes

CodeBuilder supplies each UNIX process with a fixed 36K byte stack when running in non-virtual memory mode (the unix kernel). Applications that define large stack-based storage should add the following lines to the associated Imakefile requesting a larger process stack when the program is linked:
#ifdef MachTenPPCArchitecture
LOCAL_LDFLAGS = -Xlstack=<stacksize>
To increase the application stack size by 100K bytes, use the command:
LOCAL_LDFLAGS = -Xlstack=100000
Refer to Section 8.0 CodeBuilder Programming Environment further information on programming under CodeBuilder.

9.4 X Window Software Frequently Asked Questions

Some frequently asked questions about the X Window Software are answered below:
You must be running wind(8) when you start the X server. Log into an account under CodeBuilder and be certain the wind process is running before launching the X server.

The X server depends on /usr/X11/bin/ present in your directory search path. Under CodeBuilder for the PowerPC, /usr/bin/X11 is soft linked to /usr/X11/bin. XMachTen, the X server binary, and all server support applications reside in this directory. If you are running a custom shell (e.g., zsh or ksh), make certain your X11 search path is set up before you start the wind process. The sample .login and .profile files in /usr/share/skel show examples of adding to your search path to include /usr/X11/bin.

You may have accidently installed the X software on a target volume other than the volume containing your CodeBuilder folders.

You may have moved your CodeBuilder folders to a subfolder on the target volume prior to installing the X Window Software. Use Finder to temporarily relocate the CodeBuilder folder to the top level of the target volume before installing the X software.

Read section "9.3.1 Preparing Your Macintosh Control Panels".

The log files /var/adm/X0msgs and /var/tmp/startXmsgs'do not exist or have the wrong permissions. The following commands illustrate how to create and set the proper permissions:
cp /dev/null /var/tmp/X0msgs
chmod 666 /var/tmp/X0msgs
The X server maintains a log file in /var/adm/X0msgs. Consult this file if you have difficulties starting or operating the X server. You can redirect entries logged to this file to the CodeBuilder Console terminal window using the command:
ln /dev/console /var/adm/X0msgs

By default, the X server uses the left-arrow for mouse button two, the right-arrow for mouse button three, the down arrow as a Control key, and the up arrow as a Meta key. When the Option key is pressed with an arrow key, the arrow key's original function is temporarily restored. When you re-map mouse button keys two and three in your .xserverrc file, all arrow keys' original functions are permanently restored. You may also use the -mo server start up option to restore normal functionality to your arrow keys.

Refer to section " Mouse Button Mapping" and the example in the sample X server start up file /usr/X11/lib/X11/xinit/xserverrc.

Both the Logitech MouseMan and the MouseSystems A/3 Optical Mouse have been tested successfully with the X server.

When the X desktop is visible, X client applications have precedence over the MacOS when competing for the limited number of colors that can be displayed simultaneously. The menu bar is drawn by the MacOS based on the best matching colors available.

Consider running the X server with no Macintosh menu bar as described in section " X Server Start Up Options".

Make certain that either the /usr/bin/X11 or /usr/X11/bin directory is in your directory search path.

You must load a French keyboard mapping file when the X server is launched to re-map the default U.S. X keyboard map. Refer to section " Keyboard Mapping".

The X server has a local database which takes precedence over the .Xdefaults file. This database originates from a previous running of the xrdb(n) program with the -load or -merge options.

You can force your .Xdefaults file to be read by the application by defining the XENVIRONMENT shell variable:
setenv XENVIRONMENT .Xdefaults 
Resources defined via XENVIRONMENT override duplicate resources contained in the X server's database.

Alternatively, the .Xdefaults file is read if the database is removed from the server:
xrdb -remove

The X server takes advantage of the Macintosh firmware cursor for maximum performance and a lively tactile response. The Macintosh cursor is limited to a fixed 16 x 16 pixel size, so when an application tries to display a cursor larger than 16 x 16 pixels, the server substitutes a standard arrow cursor. The X server currently does not support color cursors with this Macintosh cursor.

Both of these problems can be avoided by using the "-swc" flag with the X server.

If you have a color monitor, you can specify a custom foreground and background color for your application using the -fg and -bg command line options. For example:
xlogo -bg yellow -fg green &
Alternatively, you can copy the default application resource file (for example, XLogo) from /usr/X11/lib/X11/app-defaults (if present) for the program you are running to your home directory and modify it to suit your tastes:
XLogo*background: green
XLogo*foreground: yellow
Refer to the manual page for the client you are running for a description of the color resources available to the application.

Note that command line options take precedence over resource definitions.

A directory of contributed (and unsupported) X client applications in CodeBuilder executable format is maintained on Internet host in the /pub/applications/X11 directory.

The application has a fixed 36KB stack size when operating in a real memory environment (unix) and may require more stack space in order to run. Increase the program's stack allocation using the example in section " Programming Notes".

The MacOS reserves all Command-Shift-number keystroke combinations for special effects. Since the default X Meta key is the Command key, the Meta-Shift-number key sequence is not delivered to the X client. Use the xmodmap(n) utility to re-map Meta to something other than the Command key.

[Top of Page ][ Appendix A1 ][ Table of Contents ]