The Definitive Guide,.

to the X Window System

Volume Eight

X Window System
I Administrator's
Guide
for XII Release4 and Release 5

by Linda Mui and Eric Pearce

O'Reilly & Associates, Inc.

 X Window System
Administrator's Guide
 Books That Help People Get More Out of Computers
X Protocol Reference Manual, 516pages
Describes the X Network Protocol which underlies all software for Version 11 of the X Window System.

XIib ProgrammingManual, 824pages

XIib Reference Manual, 1144pages
Complete programming and reference guides to the X library (Xlib), the lowest level of programming
interface to X.

X WindowSystem User's Guide

Orients the new user to window system concepts,provides detailed tutorials for many client programs, and
explains how to customize the X environment.
Standard Edition, 752 pages
Motif Edition, 734pages

X Toolkit Intrinsics ProgrammingManual

Complete guide to programming with Xt Intrinsics, the library of C languageroutinesthat facilitate the design
of user interfaces, with reusable components called widgets.
Standard Edition, 624 pages
Motif Edition, 714 pages

X Toolkit Intrinsics Reference Manual, 91s pages

Complete programmer's referencefor the X Toolkit.

Motif Programming Manual, 1042

pages
Complete guide to programming for the Motif graphical user interface.

XView ProgrammingManual, 798pages

XView Reference Manual, 292pages
Complete information on programming with XView, an easy-to-usetoolkit that is widely available.

TheX Window Systemin a Nutshell,330pages

A single-volume quick referencethat is an indispensablecompanionto the series.

Contactus for a catalog of our books, for orders, or for more information.

O'Reilly & Associates, Inc.

103 Morris Street, Suite A, SebastopolCA 95472
(800) 998-9938 US/Canada 707-829-0515 overseas/local 707-829-0104 Fax
 Volume Eight

X Window System
Administrator's Guide

forX Version 11

By Linda Mui and Eric Pearce

O'Reilly & Associates, Inc.

X Window System Administrator's Guide

Copyright © 1992O'Reilly & Associates,Inc. All rights reserved.

Printed in the United States of America.

Editor: Tim O'Reilly

Printing History:

October 1992: First Edition.

February 1993: Minor Corrections.

Many of the designationsusedby manufacturersand sellers to distinguish their products are claimed as
trademarks. Where those designationsappearin this book, and O'Reilly and Associates,Inc. was awareof a
trademark claim, the designationshave been printed in capsor initial caps.

While every precaution hasbeentaken in the preparationof this book, the publisher assumesno responsibility
for errors or omissions, or for damagesresulting from the useof the information contained herein.

This book is printed on acid-free paper with 50% recycled content, 10-15% post-consumerwaste. O'Reilly &
Associatesis committed to using paper with the highestrecycled content available consistentwith high quality.

Book Alone: ISBN 0-937175-83-8 With Compact Disk: ISBN 1-56592-052-X

 Table of Contents

Page

Preface XIX

How to Use this Book xix

Assumptions xxi
Related Documents xxi
Font Conventions Used in This Book xxii
Request for Comments xxiii
Bulk Sales Information xxiii
Acknowledgments xxiii

Chapter 1 An Introduction to X Administration 3

1.1 The Design of XI1 3

1.1.1 Display Servers 4
1.1.2 Clients and Resources 6
1.1.3 Toolkits and GUIs 7
1.2 X Administration 8
1.2.1 Installing X 8
1.2.2 Supporting Users 9
1.2.3 Maintaining Software 9
1.2.4 Maintaining Multiple Machines 10
1.2.5 A "Philosophy" of X Administration 10

Chapter 2 The X User Environment 13

2.1 The Configured X Session 13

2.1.1 The Twilight Zone 16
2.2 Componentsof the X Environment 18
2.2.1 Window Managers 18
2.2.2 Customizing Clients 20
2.2.2.1 The -fn Command-line Option 20
2.2.2.2 The -geometry Command-line Option 20
2.2.2.3 Specifying Colors 23
2.2.2.4 Using Resources 24
2.2.3 The Startup Script 25
2.2.3.1 The Foreground Process 26
2.3 The Shell Environment... .. 27
 2.3.1 Setting the DISPLAY Variable 27
2.3.1.1 Complications with Display Names 28
2.3.2 Redefining the SearchPath 29
2.3.2.1 Setting the SearchPath for OpenWindows Support 30
2.3.2.2 Setting the SearchPath for Mixed Environments 30
2.3.3 xterm Issues 31
2.3.3.1 xterm and Terminal Emulation 31
2.3.3.2 The resize Client 31

2.3.3.3 xterm and the Login Shell (C Shell) 33

2.3.4 Starting Remote Clients 34
2.3.4.1 Starting a Remote Client with rsh 35
2.4 StartupMethods 37
2.4.1 xinit and startx 38
2.4.2 Differences Between .xinitrc and .xsession 39
2.5 Related Documentation .., .. 39

Chapter 3 The X Display Manager 43

3.1 xdm Concepts 44

3.2 xdm Configuration Files 46
3.3 xdm the Easy Way 48
3.4 Troubleshooting xdm 49
3.5 Customizing xdm 51
3.5.1 The Master Configuration File (xdm-config) 51
3.5.2 Listing X Servers (the Xservers File) 53
3.5.2.1 Xservers Syntax 53
3.5.3 xdm Host AccessControl: the XaccessFile (R5 Only) 55
3.5.3.1 Direct and Broadcast Access 56
3.5.3.2 Indirect Access and the Chooser 57
3.5.3.3 Using Macros 59
3.5.3.4 Advantages and Disadvantagesof the Chooser 59
3.5.4 The Xresources File 60
3.5.4.1 Configuring the Login Box 60
3.5.4.2 The xconsole Client 62
3.5.5 Starting Up Individual X Sessions (the Xsession File) 63
3.5.5.1 No Home Directory? (R5) 64
3.5.6 Display Classes 65
3.6 Testing Your xdm Setup 66
3.6.1 Resetting the Keyboard 67
3.6.2 Restarting xdm Using xdm-pid (R4 and Later) 68
3.6.3 Rereading xdm Configuration Files (R3) 68
3.7 Permanent Installation of xdm 69
3.8 Related Documentation .. ... 70

VI
Chapter 4 Security 73

4.1 Host-based Access Control 74

4.1.1 The /etc/Xn.hosts File 74
4.1.2 The xhost Client 75
4.1.3 Problems with Host-based Access Control 76
4.2 Access Control with MIT-MAGIC-COOKIE-1 77
4.2.1 Using MIT-MAGIC-COOKIE-1with xdm 78
4.2.2 The xauth Program 79
4.2.3 Using MIT-MAGIC-COOKIE-1with xinit 81
4.2.4 xauth vs. xhost 82
4.3 The XDM-AUTHORIZATION-1 Mechanism (R5) 83
4.4 TheSUN-DES-1 Mechanism (R5) 84
4.4.1 Public Key Encryption 85
4.4.2 Prerequisitesfor Using SUN-DES-1 86
4.4.3 Using SUN-DES-1with xdm 88
4.4.4 Using SUN-DES-1with xinit 89
4.4.5 Adding Another User with SUN-DES-1 91
4.4.6 xterm and SUN-DES-1 92
4.4.7 Troubleshooting SUN-DES-1 92
4.5 xterm and Secure Keyboard 93
4.6 Other Security Issues 94
4.6.1 The Console xterm (R4 and Earlier) 94
4.6.2 The Console and xdm (R5) 95
4.6.3 Hanging the Server Remotely (R3) 96
4.6.4 Reading the Framebuffer (Sun Workstations) 96
4.6.5 Removing Files in /tmp 97
4.6.6 The Network Design 97
4.7 Related Documentation ... ... 98

Chapter 5 Font Management 101

5.1 Fonts on the X Window System 101

5.1.1 xlsfonts 103
5.1.2 xfd 103
5.1.3 xfontsel 104
5.1.4 The Font Path 105
5.1.5 The Font Directory File 106
5.1.6 The fonts.scaleFile (R5 only) 107
5.1.7 Wildcards 108
5.1.8 Aliases 108
5.1.8.1 The FILE_NAMES_ALIAS Alias 109
5.2 All About Fonts 110
5.2.1 Bitmap VersusOutline Fonts 110
5.2.2 Font Formats 111
5.2.3 Format Conversion Tools 112
5.3 Adding New Fonts 114

vii
 5.3.1 Adding a Single Font 114
5.3.2 Adding Multiple Fonts 115
5.3.2.1 Multiple Font Example 116
5.3.3 Problemswith Running Vendor-specific Clients 117
5.3.4 DECWindows Examples 118
5.3.4.1 Aliasing 119
5.3.4.2 DECWindows Conversion 120
5.3.5 AlXWindows Example 121
5.3.6 OpenWindows Example 123
5.3.6.1 Aliasing 124
5.3.6.2 OpenWindows Conversion 125
5.3.6.3 Converting from XI 1/NeWS to PCF or SNF 125
5.3.6.4 More Conversions 126
5.4 Providing Fonts Over the Network , 127
5.5 The R5 Font Server 127
5.5.1 The Configuration File 128
5.5.2 Installing the Font Server 130
5.5.2.1 Testing By Hand 131
5.5.2.2 Changing BSD Boot Files 131
5.5.2.3 Changing SystemV Boot Files 132
5.5.2.4 Changing AIX Boot Files 133
5.5.3 Font Server Name Syntax 133
5.5.4 Debugging the Font Server 134
5.5.5 Font Server Clients 135
5.5.6 The Font Path and the Font Server 136
5.5.7 Hostname Aliases 138

5.5.8 A Font Server Example 138

5.6 Related Documentation .., .. 140

Chapter 6 Color 143

6.1 Color Specification in Release4 and Earlier 144

6.1.1 RGB Color Names 144
6.1.2 Numeric Color Values 145

6.1.3 Adding Your Own Color Names (RGB) 146

6.1.4 Fixing a Corrupted Color Database 147
6.2 Color Specification in Release5 (Xcms) 147
6.2.1 Xcms Color Names 148
6.2.2 Adding Your Own Color Namesin Xcms 150
6.2.3 Xcms DatabaseExample 151
6.2.4 Device Profiles 152
6.3 Related Documentation .., .. 153

VIII
Chapter 7 X Terminals 157

7.1 Buying an X Terminal: What's What 157

7.1.1 Monitors 157
7.1.1.1 Screen Size 158
7.1.1.2 Resolution 158

7.1.1.3 Depth 159

7.1.1.4 Refresh Rate 159
7.1.2 Keyboard and Mouse 159
7.1.3 X Server Software 160
7.1.4 Special Features 161
7.1.5 Memory Configuration 161
7.1.6 Network Interface 162

7.2 X Terminal Setup 163

7.3 Network Setup 164
7.3.1 Getting the IP Address Using RARP 165
7.3.2 Getting Information Using BOOTP 165
7.3.3 Trivial File Transfer Protocol (TFTP) 167
7.3.4 Setting Up the Network on the X Terminal 168
7.3.5 Debugging Hints 168
7.3.5.1 Error Messages 169
7.3.5.2 Updating the arp Table 169
7.3.5.3 Name Server Problems 169
7.4 Fonts on X Terminals 170
7.4.1 Font Formats 170
7.4.2 The Font Server (R5) 171
7.4.3 Choosing TFTP or NFS for Font Access 171
7.4.3.1 Reading Fonts Using TFTP 171
7.4.3.2 Reading Fonts Using NFS 172
7.5 Configuring for the X Display Manager 173
7.5.1 Configuring the X Terminal for xdm 173
7.5.2 Configuring an R5 Host 174
7.5.3 Configuring an R4 Host 174
7.5.4 Configuring xdm Without XDMCP 174
7.5.5 Setting Up Server AccessControl 175
7.6 Remote Configuration of X Terminals 175
7.6.1 Remote Configuration on NCD Terminals 176
7.6.2 Remote Configuration on Visual Terminals 177
7.6.3 Remote Configuration on Tektronix Terminals 178
7.7 Reconfiguring the Host 178
7.7.1 Increasing the Number of Processes 178
7.7.2 Increasing the Number of Pseudo-ttys 179
7.7.3 Increasing the Amount of Swap Space 180
7.7.3.1 Swapping to a File 180
7.7.3.2 Swapping to a Disk 180
7.8 Related Documentation .., ..181

IX
Chapter 8 Building the X Window System 185
8.1 Installation Issues 185
8.1.1 Should You Use MIT Source? 185
8.1.2 Typesof Vendor-supplied X Distributions 186
8.1.2.1 X from Your OS Vendor 187
8.1.2.2 X from a Third Party 187
8.1.3 X Source Code from MIT 188
8.1.4 Complete or Client-only Distribution? 189
8.1.5 Installing Multiple X Releases 189
8.2 SourcePreparation 191
8.2.1 Do You Have EnoughDisk Space? 191
8.2.2 Is Your Platform Supported? 192
8.2.3 Applying OS Patches 194
8.2.4 Applying X Patches 194
8.2.5 Creating a Link Tree (Optional) 196
8.3 Simplest CaseBuild 197
8.4 Host Problems 198

8.4.1 Disk Space 198

8.4.1.1 Changing the tmp Directory Using TMPDIR (Ultrix and HP-UX) 199
8.4.1.2 Changing the tmp Directory Using -temp (SunOS) 200
8.4.2 SharedLibrary Installation (SunOS) 200
8.4.3 NFS Installation 201
8.4.3.1 NFS Installation Without Root Access 201
8.4.3.2 Installation Over the Network (rdist) 203
8.4.4 Installing the termcap or terminfo Definition for xterm 203
8.5 Simple Configuration 204
8.5.1 Configuration Parameters 205
8.5.1.1 site.def 205
8.5.1.2 The ProjectRoot Flag 207
8.5.1.3 The Platform Configuration File (platform.cf) 208
8.5.2 Configuration Example 1 210
8.5.3 Configuration Example 2 211
8.5.4 Configuration Example 3 212
8.5.5 Configuration Example4 212
8.5.6 Configuration Example 5 213
8.5.7 Other Build Flags 213
8.5.7.1 xterm Build Flags 214
8.6 Building Programs After X Is Installed 214
8.6.1 xmkmf 214
8.6.2 Include Files 215
8.6.3 Libraries 216
8.7 More About imake 216
8.7.1 The make Program 216
8.7.2 The C Preprocessor 217
8.7.3 Imake Syntax 219
8.7.3.1 Comments in imake 219
8.7.3.2 Multi-line Macros (@@) 220
 8.7.3.3 Concatenating Macros 221
8.7.3.4 Dealing with Tabs 222
8.7.4 imake Configuration Files 222
8.7.4.1 A Quick Tour of Files Used by imake 223
8.7.5 Using imake to Build XI1 224
5.8 Porting Hints 226
8.8.1 Undefined Symbols or Functions 226
8.8.1.1 Missing Header Files 226
8.8.1.2 Missing Function Definitions 226
8.8.2 Searching for PreprocessorSymbols 228
5.9 Related Documentation ... .. 230

Appendix A Useful Things to Know 233

A.I The comp.windows.x Newsgroup 233

A.2 How to ftp a File 234
A.2.1 Getting Files Using ftpmail 235
A.2.2 BITFTP 237
A.3 The xstuff Mail Archive Server 237

A.4 Unpacking Files 238

A.5 Making a FilesystemAvailable via NFS 239
A.6 How to Add a Host 239

A.6.1 Adding a Host to /etc/hosts 239

A.6.2 Adding a Host Using MS 240
A.6.3 Adding a Host Using DNS 240
A.7 Adding an Ethernet Address 242
A.8 Printing Documentation in the MIT X Distribution 242
A.9 Converting a Number Into Hexadecimal and Back 243
A.10 Configuring a Sun as an X terminal 243
A. 11 Using More than One Frame Buffer Under SunOS 244

Appendix B Compiling Public Domain Software 247

B.I Finding the Sources 247

B.I.I Using an Archie Server 248
B.1.2 Get the FAQ 250
B.1.3 The Usual Suspects 250
B.2 An Example: xarchie 251
B.2.1 Getting the xarchie Sources 251
B.2.2 Untarring the Sources 252
B.2.3 Editing the Imakefile 254
B.2.4 Compiling the Source 255
B.3 Using Patches 259
B.4 Another Example: xkeycaps 264
B.5 Related Documentation .. .. 268

XI
Appendix C X on Non-UNIX Platforms 271

C.I X on DOS-based PCs 272

C.I.I Requirementsfor PC X Servers 272
C.I.2 Installing and Configuring PC X Servers 273
C.1.3 Problems Particular to PC X Servers 274
C.2 X on Macintosh Computers 275
C.2.1 Macintosh-based X Servers 275
C.2.2 MacTCP and the Communications Toolbox 276
C.3 X on NeXT Computers 277

Appendix D Resources and Keysym Mappings 281

D.I Using Resources 281

D.I.I Resource Definition Syntax 281
D.I.1.1 Loose and Tight Bindings 282
D.I.1.2 The-name Command-line Option 283
D.I.1.3 xterm Versus XTerm 283
D.I.2 Where Resources Are Defined 285
D.I.3 Advantages of xrdb 287
D.I.4 Translation Tables 288
D.2 Defining Keys and Button PressesWith xmodmap 290
D.2.1 Using xev to Learn Keysym Mappings 292
D.3 Related Documentation ., .. 293

Appendix E The Components of X Products 297

E.I MITXI1 Release 5 298

E.2 OSF/Motif 299
E.3 Sun OpenWindows 300
E.4 DECWindows 301
E.5 AlXWindows 302
E.6 Silicon Graphics 302
E.7 A Guide to XI1 Libraries .. .. 303

Appendix F Getting Xll 307

F.I Where Can I Get XI1R5? 307

F.2 Where Can I Get Patches to XI1R5? 311
F.3 Where Can I Get XI1R4? ... ..311

XII
Appendix G Error Messages 315
G.I X Errors 315
G.2 UNIX Errors 318
G.3 Compilation Errors 320

XIII
 Figures

Page
1-1 An X server with clients from multiple hosts 5
2-1 A configured X session 13
2-2 A root menu 14
2-3 An unconfigured X session 16
2-4 Starting a new client 17
2-5 xclock window over xterm window 17
2-6 Starting the window manager 19
2-7 xterm window with new font 21
2-8 A window with a specified geometry 22
2-9 An xterm window in reversevideo, decoratedby twm 23
2-10 vi using only part of a window 32
2-11 Logging in with xdm 37
2-12 Starting the X server with xinit 38
3-1 xdm flow chart 44
3-2 Default xdm configuration files 46
3-3 xdm login box 48
3-4 Default xdm environment 49
3-5 XDMCP Direct, Indirect, and Broadcast queries 56
3-6 The chooser 58
3-7 An example chooserbox 58
3-8 Chooser box with an R4 host 60
3-9 Adapted xlogin greeting 62
4-1 Host-based access control 74
4-2 XDMCP and the access code 77
4-3 User-based access control 78
4-4 Propagating the magic cookie betweentwo hosts 80
5-1 Componentsof a font name 102
5-2 xfd 104
5-3 xfontsel 105
5-4 Font conversion utilities 113
5-5 dxcalendar with the wrong fonts 119
5-6 dxcalendar with aliases 120
5-7 cm without aliases 123
5-8 cm with aliases 124

6-1 Red, green, and blue color guns 143

6-2 Xcms vs. RGB color specification 149
6-3 xtici Edit menu 150
8-1 oclock without the SHAPE extension 190
8-2 oclock with the SHAPE extension 190
8-3 Recursive make 218

8-4 Files processedby imake 223

B-l xarchie window 258
B-2 xkeycaps window 267
D-l xcalc window ... .. 289

xiv
 Tables

Page
8-1 cpp Symbols 228
B-l Archie Serversas of January 3, 1992 248
E-l X Distribution Directories 297
E-2 MIT XI1R5 Files 298
E-3 Motif Files (Motif 1.1.x) 300
E-4 OpenWindows Files (Sun4, SunOS4.1.1) 300
E-5 OPEN LOOK Files 301
E-6 DECWindows Files (DecStation, Ultrix 4.2) 301
E-l AlXWindows Files (RS/6000, AIX 3.2) 302
E-8 Graphics XI1 Files (Indigo, IRIX 4.0) 302
F-l North America Anonymous ftp 307
F-2 Europe/Middle East/Australia Anonymous ftp 308
F-3 Japan Anonymous ftp 308
F-4 UUCP 309
F-5 Other File Transfer Methods .. ..309

xv
 Preface

This preface outlines who should be reading this book, and what readers
should expect from it.

In The Preface:

How to Use this Book xix

Assumptions xxi
Related Documents xxi
Font Conventions Used in This Book xxii
Request for Comments xxiii
Bulk Sales Information xxiii
Acknowledgments xxiii
 Preface

UNIX machines can be difficult to maintain. Traditionally, UNIX administration has meant
juggling dozens of configuration files and supporting end userswho may not understandhow
the systemactually works. Becauseit is infinitely flexible, UNIX can be a power-user's para-
dise and a beginner's nightmare, with the administrator sandwiched somewherein between.
This book is designed to bridge that gap. It provides detailed information and proceduresfor
setting up a system that gives usersaccessto the full power of X, without the headaches.

How to Use this Book

This book has beenwritten to be useful to as many types of X Window Systemadministrators

as possible. Some readersare full-time system administrators at large academic sites who are
well-versed in UNIX and X, but are always looking for new tips. Other readersare part-time
administrators at smaller sites who know a good amount about UNIX and X but are tired of
always having to reinvent the wheel. Still other readers are workstation owners who are
forced to do their own administration, interested only in getting their system running
smoothly.

Since this book is aimed at such a wide audience, not all readers will be interested in every
chapter. If we tell you about platforms you don't use, issues that aren't relevant to you, or
describe basic concepts with more detail than you need, we hope that you'll be patient and
just skim through to find what you need to know.
Chapter 1, An Introduction to X Administration, briefly introduces the design of X,
with emphasis on the administrative issues that arise out of that design.
Beginners to X and X administration should read this chapter.
Chapter 2, The X User Environment, describesissuesfor configuring the X user envi-
ronment. Readerswho need to set up new users should read this chapter.
This chapter is also a good place for readers who are new to X and need to
learn more about how it works from the user's point of view.

Chapter 3, The X Display Manager, describes the X Display Manager (xdm) and how
to configure it. Readers who are interested in running xdm should read
this chapter.

Chapter4, Security, describes security issuesfor X. We recommend that managersof

all networked X environments study this chapter.

Preface xix
Chapter5, Font Management, describes issues with using and adding fonts, both
under the standardmethods and through the XI1 Release 5 font server.
Readers who are interested in adding fonts to their system or using a
networked font server should read this chapter.

Chapter6, Color, describeshow color works in X, and how to add new colors in both
the RGB and Xcms color databases. Readers who have color displays may
want to read this chapterto learn more about how color works and how it
can be manipulated.

Chapter7, X Terminals,describesthe different types of X terminals,how to setup the

network for new X terminals, how to install fonts on the host, and how to
reconfigure the host machine to support more processes. If you use or
intend to use X terminals at your site, you should read this chapter.
Chapter 8, Building the X Window System,describesthe issuesinvolved with building
X from source. Readers who must build X from source, or who are inter-
ested in understanding more about the basic structure of the X software
should read this chapter.

Appendix A, Useful Things to Know, documents various "miscellaneous" procedures

and odds-and-endsthat many users will already be familiar with, but
which we want to include for the benefit of those users who are not. This

appendix shows how to ftp files, how to export NFS directories, how to
add a hostname to your name server, etc. Browse through this chapter at
least once to see if there's anything new in there; throughout the book, we
refer to sectionsof this chapterwhen applicable.
Appendix B, Compiling Public Domain Software, a tutorial, describes how to find and
compile public domain software. Readers who aren't familiar with this
process should read this appendix.

Appendix C, X Serverson Non-UNIXPlatforms, briefly describesissueswith using XI1

servers on DOS-basedPC and Apple Macintosh machines.Readerswho
are interestedin running X on theseplatforms should read this appendix.
Appendix D, Resourcesand KeysymMappings, provides a more thorough description of
resourcesand keysym mappings. You can't work with X without needing
to understand these topics at least a little bit, so we include some back-
ground here. Some of this material duplicates what you'll find in Volume
Three,X Window SystemUser's Guide, but we also give some useful tips
and advancedinformation for administrators. So even if you are familiar
with how to use resources,you may want to scan this appendix.
Appendix E, The Componentsof X Products, lists the directory structure of MIT XI1
and various vendors' implementations.Use this appendix as needed.
Appendix F, Getting XI1, lists sites that have made the XI1 source code available.
Reprinted from the comp.windows.xnewsgroup Frequently Asked Ques-
tions list. Use this appendix if you needto obtain the X11 sourcecode.
Appendix G, Error Messages, lists some of the error messagesusers may encounter.
Refer to this appendix when troubleshooting.

XX TheX WindowSystemAdministrator'sGuide
Assumptions

To get the most out of this book, you should be familiar with UNIX and with general princi-
ples of system and network administration. If you have never administered a UNIX systemor
a TCP/IPnetwork, see the Nutshell Handbooks Essential SystemAdministration by yEleen
Frisch (O'Reilly & Associates, 1991) and TCP/IP Network Administration by Craig Hunt
(O'Reilly & Associates, 1992).

A firm understandingof X is helpful. If you have never used X, you should have a copy of
Volume Three, X Window SystemUser's Guide, close at hand. However, we have included a
lot of background information on X for the benefit of readers who have not had a formal
introduction to X.

Readers are not expected to have any C programming experience, although UNIX shell pro-
gramming experiencemay come in handy for understandingsome of the examples.
Readersare assumedto have the X manpagesavailable, or to be able to obtain them easily.
(These pages are reprinted in the X Window System User's Guide and are also available
online with many X distributions.) This book does not attempt to replace the X manpages.

Related Documents

The following Nutshell Handbooks published by O'Reilly & Associates, Inc. may also be
helpful:

Managing Projects with make, by Andy Oram and SteveTalbott

Managing NFS and NIS, by Hal Stern
Practical UNIX Security, by Simson Garfinkel and Gene Spafford
System Performance Tuning, by Mike Loukides
DNS and BIND, by Cricket Liu and Paul Albitz
The Whole Internet User's Guide and Catalog, by Ed Krol
TCP/IP Network Administration, by Craig Hunt

Several other books and a journal on the X Window System are available from O'Reilly &
Associates, Inc.:

Volume Zero - X Protocol Reference Manual

Volume One - Xlib Programming Manual
Volume Two - Xlib ReferenceManual
Volume Three -X Window SystemUser's Guide, Motif and Standardeditions
Volume Four - X Toolkit Intrinsics Programming Manual, Motif
and Standard editions
Volume Five - X Toolkit Intrinsics Reference Manual
Volume Six - Motif Programming Manual
Volume Seven - XView Programming Manual

Preface xxi
 PHIGSProgramming Manual
PHIGS Reference Manual
Quick Reference - The X Window System in a Nutshell
The X Resource

In addition, each chapterends with its own topical list of related documentation.

Font Conventions Used in This Book

Italics are used for:

" UNIX pathnames,hostnames,domain names,client and UNIX command names,

and command-line options

" New terms where they are defined

" Emphasis

Typewriter Font is used for:

" Output in an example, i.e., prompts and messagesfrom commands

" The contents of configuration files

" Flags used to build X

" Display names

" IP addresses

" Resource names

Bold Typewriter Font is used for:

" Input in an example, i.e., what the user types on a commandline

" Highlighting lines of code

Helvetica Italics are used for:

" Titles of figures and tables

Helvetica Bold is used for:

" Chapter and section headings

xxii The X Window System Administrator's Guide

Request for Comments

To help us provide you with the best documentationpossible, please write to tell us about any
flaws you find in this manual or how you think it could be improved.
Our U.S. mail address,e-mail address,and phonenumbersare as follows:
O'Reilly & Associates,Inc.
103A Morris Street
Sebastopol,CA 95472
800-998-9938
international +1 707-829-0515
fax+1 707-829-0104

UUCP: uunetlora.comlnuts Internet: [email protected]

Bulk Sales Information

For information on volume discounts for bulk purchase, call O'Reilly & Associates, Inc. at
800-998-9938, or send e-mail to [email protected] (uunetlora.comllinda).

For companies requiring extensive customization of the book, source licensing terms are also
available.

Acknowledgments

Though it might seem a logical addition to our X Window System series, we didn't think up
this book on our own. It was a customer call that set the project in motion. Scott Hunter of
Oracle called up to ask if we had anything on X administration in the works. We said we
didn't, but that we thought it was a great idea. Scott and his co-worker Mike Riggs outlined
for us the kinds of problems they were facing that made such a book a necessity. We would
like to thank Scott and Mike for their initial efforts in conceiving the book, as well as Mary
Beth Hagan and Marilyn Grady, who did someof the initial researchand writing before it fell
into our laps.

We would also like to thank the technical reviewers for the first edition of this book. They
were David Lewis; Jeffrey Vogel; Mike Braca of Visual Technology; Stephen Gildea of the
X Consortium; Liam Quin and Ian Darwin of Softquad, Inc.; Doug Klein, Dave Lemke, and
the staff at Network Computing Devices; Dave Curry of Purdue University; Dinah McNutt of
Tivoli Systems; Miles O'Neal of Pencom; Jim Frost of CenterLine Software; Jon Werner of
International Business Machines; Spencer Murray of Silicon Graphics, Inc.; Joe Ilacqua;
Valerie Quercia, David Flanagan and Adrian Nye of O'Reilly & Associates;Al Tabayoyanof
North Valley Research;and UpeshPatel of The Santa Cruz Operation.
Our thanks to each of thesereviewers for taking the time to make this book useful and com-
plete. Additional thanks to David Tolman of Human Designed Systemsand R. Lee Rainey of
Tektronix for supplying information on their company's X terminals, and to Garry Paxinosof
MetroLink, Inc. and Greg Mudge of PhoeniX Software Solutions for helping to clear up some

Preface xxiii
details about running X on PC hardware. Also, thanks to Dave Curry, Chris Calabreseof
AT&T Bell Labs, Joe Ilacqua, and David Lewis for supplying random number generation
methods for use with the discussion of MIT-MAGIC-COOKIE-1in Chapter 4. David Lewis
was also kind enough to allow us to reprint the material in Appendix F from the comp.win-
dows.x Frequently Asked Questions list that he maintains.

Several vendors were kind enough to lend us software or hardware for testing purposes.
These were Silicon Graphics, Visual Technology, Human Designed Systems,Unipress Soft-
ware, White Pine Software, Network Computing Devices, Locus Computing Corporation,
Unipress Software, Vision Ware Ltd., Quarterdeck Office Systems,FTP Software, Humming-
bird Communications Ltd., and Starnet Communications.

We would also like to thank those who worked on the production of the book. At O'Reilly &
Associates,we would like to thank Gigi Estabrook for her initial copy-edit, Chris Reilley for
the figures, Ellie Cutler for indexing, and RosanneWagger and Mike Sierra for production of
the final copy. We would also like to thank Lenny Muellner for tools support and for allow-
ing us to disrupt his life wheneverwe had the urge to make screendumps.
Finally, we would like to thank our editor, Tim O'Reilly, for his initial trust in us and for his
patienceduring the countlessmonths it took us to put the book together.
Of course, we alone take responsibility for any errors or omissions that remain.

xxiv The X Window System Administrator's Guide

 1

An Introduction to X Administration

This chapter provides an introduction to X and to X administration.

In This Chapter:
The Design of X11 3
Display Servers 4
Clients and Resources 6
Toolkits and GUIs 7
X Administration 8
Installing X 8
Supporting Users 9
Maintaining Software 9
Maintaining Multiple Machines 10
A "Philosophy" of X Administration 10
 1
An Introduction to X Administration

Administrators make things work. On the surface, the X Window System is just one more
software package that the administrator needs to install, maintain and support for users. X
runs on any architecture, so there are fewer differences betweensystemsthan with most soft-
ware. What makes X different from other packages,however, is that it provides a great deal
of configurability. It's relatively easyto get X to run on your site with its default settings, but
it requires a bit more homework to take advantageof its flexibility and create a secure, cen-
trally-maintained environment for users.This book doesthe homework for you.
Administrators need to know how X works before they can figure out how to make it work
for them. This chapterprovides an introduction both to X and to X administration.

1.1 The Design of X11

The X Window System, called X or XI1 for short, is a network-basedgraphics window sys-
tem that was developed at the MassachusettsInstitute of Technology. X is basedon the cli-
ent/server model, in which the application program (the client) does not directly accessthe
display, but communicateswith an intermediary display program (the server).
One important feature of the client/server model is that the client and server programs can
communicate over a network. They do not need to run on the same machine, or even in the
samebuilding. This meansthat an X display is an ideal front end for a distributed computing
environment. A system administrator might open windows on each of a dozen machines she
is maintaining; a financial analyst at a Wall Street firm might have a spreadsheetin one win-
dow, Quotron data "off the wire" in another,and a custom mainframe-basedanalysis program
in another.

The client and server communicate using the X Protocol, which can run on top of UNIX
domain sockets,TCP/IP,or DECnet. Technically, the X Protocol is the true definition of X.
However, when we refer to X, we often mean not only the protocol but also the widely avail-
able implementation of clients, serversand libraries that use that protocol.
Since the client and server can run on different machines,the local display machine can get
away with running a server program and nothing else. X servers can run on single-tasking
DOS-basedPCs, which connect across the network to multi-user systemscapable of running
multiple graphical applications. More importantly, this feature has led to the development of
low-cost X terminals, designed specifically for running X servers. Using X terminals, a

An Introduction to X Administration
 company can give multiple usersthe ability to run graphics-intensive programs,without hav-
ing to buy each user a machine powerful enough to execute the graphics programs them-
selves.

X has great commercial potential becauseX can be ported to any architecture, operating sys-
tem, or display type. Servershave beenwritten for all sorts of architectures,under all sorts of
operating systems,for all types of displays.The only requirement is that there be a keyboard,
a graphic display, and an input pointer (such as a mouse). And becausethe server handlesthe
hardwareand operating-systemdependencies,client programscan be almost completely por-
table.

Currently, most client programsrun on some flavor of the UNIX operating system,but they
have also long been available undermany other operating systems(such as VMS), and recent
products now run X clients (as well as servers) on DOS and Macintosh machines. Further-
more, clients have been written to be heavily dependent on programming libraries. This
means that once the libraries are ported to another operating system, clients using those
libraries should be easily ported as well.

X was developed at the MassachusettsInstitute of Technology and is maintained by a non-

profit consortium of vendors and universities. The sourcecode to XI1 is free. As a result, X
has led to an explosion of free software not seensince the heyday of Berkeley UNIX develop-
ment.

The fact that X was developed by a consortium and had to meet the sometimesconflicting
needs of many different vendors, does, however, lead to a few complications. At times, it
seemsthat the developershave gone overboard to make X flexible, configurable and extens-
ible, so that it could be adapted to the needs of whatever platform and environment it is
ported to. However, in the end, it is hard to fault the bias towards flexibility. The almost uni-
versal adoption of X is a tribute to just how insightful thosedesign decisions were.
One very concrete expression of X's political heritage is that X itself is a no-frills window
system. Rather than choose between competing graphical user interfaces (GUIs), the X
designerschoseto articulate "mechanism not policy." That is, they provided basetechnology
for manipulating windows, but didn't insist on a particular "look and feel." X keepsthe GUI
distinctly separatefrom the window system itself. Several GUIs (notably those basedon the
OSF/Motif and OPENLOOK specifications)have already beenbuilt upon XI1. What's more,
becauseX doesn't have a GUI to get in the way, it has been integrated with other window
systemssuch as Microsoft Windows and the Macintosh Finder. In such implementations,X
windows exist side-by-side with the native windows of that GUI.

1.1.1 Display Servers

Client-server terminology often seems"backwards" to people who are new to X. Since the X
display runs on a local machine on the user's desk, you might think that the X display should
run the X client program. People are used to thinking of servers as something they access
acrossthe network (such as file or print server).

X Window System Administrator's Guide

If you think about it more carefully, though, you realize that the terminology is exactly right.
The X serveris a display server. It makes your display and keyboardavailable to applications
running on other machinesacross the network. The fact that you can and often do run clients
locally doesn't make the display server any less a server. Clients must still connect to it to
make use of the services(display and keyboard) it manages.
The X display server accepts connections from any number of X application clients. These
clients might run on any machineon the network, as shown in Figure 1-1.

Supercomputer

ersonal Computer
*"
i
8«"1itJf / ,-- -"
Local *"-" Large
Mnicomp
Client

DisplayServer

Figure 1-1. An X server with clients from multiple hosts

An X servercan be written for any sort of graphic display. Thesedisplays, each consisting of
a pointing device, a keyboard and at leastone monitor, can differ in several ways.
" Monitors have different screen sizes and different resolutions. Some monitors have color
support. A servermight support anywherefrom 1 to 24 bits of color per pixel.
" The pointing device might be a mouse, a touchscreen, or a pen. Most displays use a
mouseas a pointing device, but the mousemight have 1, 2, or 3 buttons.
" Different keyboards have different layouts, and each key generates different control
sequences.You can depend on alphanumeric keys on U.S. or European keyboards,but
you can't dependon there being function keys, an ALT key, or a numeric keypad.

An Introduction to X Administration
 On other window systems,you might be able to configure this information directly into the
application at installation time, since there's only one display that the program can access.X
clients, however, need to be able to run with all possible servers. The X server therefore
needsto mediatebetweenclients and the specifics of the display.

For the output device-i.e., the monitor-the servernot only needsto know how to draw to
the display as specified by the client, it also needs to be able to tell the client the screen
dimensions or whether color is supported. If a user has more than one monitor, each monitor
can be used as a separate screen of the display.

Input devices (the mouse and keyboard) can also differ. In order to insulate clients from
these differences, the server maintains a mapping between physical buttons and keys and cor-
responding logical identifiers. For example, the code generated by each key is assigneda
symbol, called a keysym. Clients refer only to keysyms, and the server performs the actual
translation between keysyms and the actual keycodes generated by a particular keyboard.
(For more information on keysyms, see Section D.2.)

1.1.2 Clients and Resources

BecauseX applications, or clients, can display on any X server on the network that allows
the connection, X applications must be configurable. However portable the X client-server
model makes an application, there are going to be dependencies and preferences that the user
needs to be able to express. A font that looks good on one display might be too small on
another; a key that is easily reached on one keyboard might be a stretch on another.

On anotherwindow system,suchas that on a Macintosh or on a PC running DOS, all applica-

tion preferences can be set at the application level. This makes sense, because the Macintosh
OS and DOS are single-useroperating systemswith only one display to connect to. All pref-
erencesmight as well be stored in the sameplace.
By necessity,X needsto deal with application resourcesmore robustly. X generally runs on
multi-user systems, so clients need to be configurable by each individual user. (Character-
basedUNIX programsalready do that using "dot" files in the user's home directory, such as
.exrc, .newsrc and .mailrc.) X clients can display on any server on the network, and each
servermay require its own preferences;so X clients also need to be configured for each indi-
vidual server. And becausebinaries are often sharedamong several different hosts,each X
client executable might be run on any number of systems,so system-specific defaults are
needed.

X applications needto be configurable at each of these levels. X applications are configured

primarily via resources.Resourcesare variables that are usedby X clients and that can be set
at the user level, system level, server level, and client level.

It is essential that a system administrator thoroughly understand the resource mechanism.

Resourcesare discussedin detail in Volume Three, X Window SystemUser's Guide. In addi-
tion, Appendix D provides a summaryof the most important points of syntax and usage.

X Window System Administrator's Guide

1.1.3 Toolkits and GUIs

X clients are built using a number of programming libraries that progressively insulate the
programmer from the details of the X protocol. The lowest layer is Xlib, which maps fairly
directly to the protocol, and requires the programmerto do a great deal of "handwork." Each
event generated by mouse movement, key presses,or graphics exposure must be handled
explicitly. Writing a graphical user interface with Xlib would be a bit like starting out with
logs when you want to build a house.For this reason, in most X clients, Xlib is used chiefly
for drawing, or in cases where the programmer needs more direct control of the dialog with
the server.

The X Toolkit Intrinsics (Xt) are built on top of Xlib. They simplify the job of building a
graphical user interface by creating support for objects called widgets. Widgets are proto-
types for common user interface elements such as scrollbars, menus, and so forth, plus other
objects that can be usedto glue theseelementstogether into a complete application window.
But Xt itself does not provide a GUI. This is the job of additional libraries that are layered on
top of Xt in turn. The three most common GUIs are provided by the Athena widgets and the
OSF/Motif and OPENLOOK specifications. What's more, even a widget set provides only
part of the GUI's look and feel. The basic framework for moving, resizing, and managing
windows is handedover to a separateprogram called a window manager.

Athena is a bare-boneswidget set originally developed by MIT as a "proof of concept" for

Xt. Athena is not terribly pretty, but is widespread becausemost of the original MIT client
programs were written with the Athena widgets. The corresponding window manager is
usually twm.

OSF/Motif is a GUI that was developed by the Open Software Foundation and is sold by var-
ious licensed resellers. (Motif source can be purchased directly from OSF.) OSF/Motif con-
sists of a set of Motif libraries and widgets, a style guide, several demo clients, and the Motif
window manager(mwm).
OPENLOOK is a GUI specification with multiple implementations. The OLIT toolkit is an
Xt-based toolkit developed by AT&T. The XView toolkit was developed by Sun directly on
top of Xlib, with an API similar to its native SunView user interface, which predated X.
XView is available in the contribl part of the MIT distribution. OpenWindows is a complete
windowing environment distributed by Sun Microsystems that is compatible with the OPEN
LOOK specification, and which includes a window managerclient called olwm.
To further complicate the picture, clients can be written using one set of widgets, yet work
with the window manager of a competing GUI. This is most common with MIT clients writ-
ten with the Athena widgets, which are often used with mwm or olwm. Fortunately, there is a
set of conventions (called the Inter-Client Communication Conventions) that ensure inter-
operability of clients and window managersfrom different X-based GUIs.

An Introduction to X Administration
 1.2 X Administration

One of the philosophiesthat X is built on is that it provides "mechanism, not policy." This is
good for developers, since it allows them to decide how X should be used.But until a single
standard emerges, it leaves users (and administrators) without much guidance. This book
hopes to come to the rescue.

One complication for usersand administrators is that there are so many different flavors of X.
There's "standard" X-that is, the client, serverand library distribution maintained by the X
Consortium at MIT. Then there are the various vendor-configured versions that are derived
from MIT XI1 but then configured for a vendor's operating systemand proprietary "look and
feel." There's OpenWindows, which runs on Sun workstations.There's Open Desktop, which
runs on PCs running SCO UNIX. There's DECWindows, which runs on DEC workstations,
and AlXWindows, which runs on IBM workstations running AIX. And many more.

This meansthat X may not look the sameon different platforms. A user who thinks he or she
has learned X may find that they're totally lost in a co-worker's environment acrossthe hall-
way. Furthermore, an administrator might have severaldifferent platforms to maintain. This
book concentrateson "standard" XI1 as distributed by MIT, but also covers conflicts with
vendor distributions of X, as well as conflicts between different releases of XI1.

Another complication is that while the X Consortium provides only "mechanism" and relies
on vendors to decide how to use it, there are some gaps where no robust, universally-
acceptedway of dealing with the mechanismhas come to light. For example, resourceshave
the potential to be a very powerful tool, but are currently difficult to understand,manipulate,
and debug. You need to know what's "under the hood" before you can use resourcesprop-
erly.

This is one of the most difficult things about X administration: you may need to know an
awful lot about how things work before you can do what you really want. This book tries to
make it easier to configure X for your site by describing procedures step-by-step. At the
sametime, we try to provide background information for readerswho continue to have prob-
lems or are interestedin knowing more.
The X sourcesprovide ample documentation,but it's often difficult to weed through the doc-
umentation tree to find what you want to know. For example, to learn how to use security fea-
tures of XI1, you need to read the xauth, Xsecurity, xhost and xdm manpagesbefore you can
begin to get an idea of how it works. This book attempts to group together everything you
need to know to get X working on your site.

1.2.1 Installing X

You can get X from your operating system vendor, or you can use the standard MIT XI1.
Which you chooseto do dependson what you plan to do with it.
If you plan to run specific clients, you may have no choice: a client might run only with a
vendor's distribution of X (such as OpenWindows),or it might run only with XI1R5 (which
at this writing is unavailable from OS vendors).

X WindowSystemAdministrator'sGuide
 If technical support matters a lot to you, you might prefer to stick with your vendor's distri-
bution of XI1. If having the "latest and greatest" is more important to you, you probably
want to build MIT XI1 with all the latest patches.
If you plan to develop your own X applications, you may want several different X distribu-
tions installed, so you can test (or port) your applications on multiple platforms. In addition
to the X distribution itself, you will probably also need other toolkits installed, such as
OSF/Motif, OLIT or XView.

Chapter8 describeshow to build XI1 from source.

In addition to the X distribution of clients, libraries and a local server, administrators need to
provide X serversfor users.X terminals are available from many different vendors. X servers
that run on top of PC and Macintosh environments are also available. Chapter 7 discusses
the issuesof choosing and installing an X terminal, and Appendix C discussesX serversthat
run on PCs, on Macintosh computers, and on NeXT computers.

1.2.2 Supporting Users

Your users might all be self-sufficient power users,or they might need their hands held with
every step. You probably have both types on your site, as well as every gradation in between.
You will need to set up default environments for the users on your site, and be preparedto
help them debug their environment when things go wrong. Rememberthat the more time you
spendon setting up templatesfor users,the faster users will be able to be productive, and the
less time you'll spend later on debugging their environments. Chapter 2 covers someof the
issuesthat you will needto addresswhen setting up a user's environment.
If you have any X terminals at your site, you should run the X Display Manager (xdiri) to pro-
vide an easy way for those users to log on and start their X sessions.You might also want to
set up xdm to control X servers running on workstations as well, since among other things,
xdm provides a way to configure user environments in a central place. Chapter 3 describes
how to set up xdm for your site.

Unless everyone at your site trusts everyoneelse, you should probably look into using secu-
rity for X serverson your site. If you are on the Internet, you should definitely use security. If
someone'sdetermined to snoop on you, they can probably get through, but there are a few
things you can do to trip up the more casual attacker. Chapter 4 describes security issues for
Xll.

1.2.3 Maintaining Software

After you have everything running smoothly on your site, you'll find that most of your time
as administrator will involve getting and installing new software, and upgrading existing
software. In addition to commercial software, sourcesto many X programs are available in
the public domain. Appendix B is a tutorial on how to find and build public domain software.

An Introduction to X Administration
 New clients often call for new fonts. These fonts have to be made available to all servers that

might run the client. Chapter 5 describes how to install new fonts and how to convert fonts
from other formats.

1.2.4 Maintaining Multiple Machines

The whole idea of X is to have many machines networked together: PCs, workstations, X
terminals, minicomputers, supercomputers,you name it. This can becomea lot of work for
administrators, since that means multiple machines to configure and maintain consistently.
One useful tool is to keep up-to-date documentation on how each machine is configured.
This is especially helpful on a large site, particularly on one with more than one administra-
tor.

But maintaining many different machines can be made much easier if you configure
machines centrally when you can. This book describes the various mechanisms X provides
for doing so. The X Display Manager can be used to maintain all X sessionscentrally. Many
X terminals can be configured remotely from a host machine. The font server, new with
XI1R5, provides a way to supply fonts to multiple servers.

1.2.5 A "Philosophy" of X Administration

If we had to come up with a "philosophy" of X administration, it would be that X is made to

fit the needsof its users. As the administrator, you have the responsibility to determineyour
users' needsand configure X accordingly.
X is installed in all sorts of environments, from universities with hundreds of student users, to
home offices with a single standalonemachine. For that reason,almost everything in X is
configurable at multiple levels. Application resourcescan be set in several different places.
You can createnew fonts and define new colors. The X Display Manager can be configured
to meet practically any need. Even the sourcecode to X is available for programmerswho
want to create their own workarounds if none already exist. The fundamental idea is that if
you don't like the way somethingworks, changeit.
From the onset, you'll see that this book is less about making X work than it is about getting
X to work for you.

10 X Window System Administrator's Guide

 The X User Environment

Administrators need to configure X environments for their users. This chap-

ter describes the issues involved in making an X environment work properly.

In This Chapter:
The Configured X Session 13
The Twilight Zone 16
Components of the X Environment 18
Window Managers 18
Customizing Clients 20
The -fn Command-line Option 20
The -geometry Command-line Option 20
SpecifyingColors 23
Using Resources 24
The Startup Script 25
The Foreground Process 26
The Shell Environment 27
Setting the DISPLAYVariable 27
Complications with Display Names 28
Redefining the Search Path 29
Setting the Search Path for OpenWindowsSupport 30
Setting the Search Path for Mixed Environments 30
xterm Issues 31
xterm and Terminal Emulation 31
The resize Client 31
xterm and the Login Shell (C Shell) 33
Starting Remote Clients 34
Starting a Remote Client with rsh 35
Startup Methods 37
xinit and startx 38
Differences Between .xinitrc and .xsession 39
Related Documentation . ..39
 The X User Environment

2.1 The Configured X Session

We set up an X environment for a new employee, Joan, whose job involves internal project
management.Joan is new to both UNIX and X. We've set up her environment so that when
she logs in via the X Display Manager, xdm, she gets an environment resembling that in
Figure 2-1.*

Top
uby:joon 26%

uby:Joan26X

Figure 2-1. A configured X session

*If you aren't already running xdm, see Section 3.3 for information on how to set it up the first time.

The X User Environment 13

" Joan gets two terminal emulator windows. The top one is labeled "Top" and the bottom
one is labeled "Bottom."

" Joan has a clock in the upper-right corner of the screen.

" Joan wants to have a calculator available all the time, since her job involves juggling
numbers.

" The rest of the windows are from a public domain application called xpostit, which Joan
can use to keep notesand reminders on her desktop.

The root window is the screen background behind the X client windows. If Joan pressesher
first mouse button while the pointer is in the root window, she gets a root menu resembling
that in Figure 2-2. We've configured her root menu so she can start new clients easily:

Terminal
Clock
Calculator

Dictionary
Solitaire

Kill Window
Iculator

Restart twm

Log Out

Figure 2-2. A root menu

By pressing down her first mouse button and then selecting the "Dictionary" option, for
example, Joancan bring up a dictionary application.
To create this environment, we neededto set up three X configuration files in Joan's home
directory, in addition to the "standard" UNIX shell startup files. The X configuration files are:
.xsession

The .xsession file is the shell script that actually starts each of the applications in
Joan's startup environment. The .xsession script reads:
#!/bin/sh

# Add /usr/local/bin to the path for this script:

PATH=$PATH:/usr/local/bin
export PATH

# Set up a pattern for the root window:

14 The X Window System Administrator's Guide

 xsetroot -bitmap /usr/include/Xll/bitmaps/dimplel
# Merge in user resources:
xrdb -merge $HOME/.Xresources

# Start some applications:

xterm -title Top -g 70x35+1+1 &
xterm -title Bottom -g +1-0 &
xclock -g -0+0 &
xcalc -g -0+298 &
xpostit -sv -g 110x50-0+200 &

# Start a window manager in the foreground:

twm

.Xresources
The .Xresources file contains resource definitions. These resources define Joan's client
preferences.Currently, Joan's resourcesare used to set somepreferencesfor her xterm
terminal emulator windows. We set her up to use a font that we think she would prefer
over the default, we turned on a scroll bar, and we set the number of lines to be saved
for scrolling to be 200. The .Xresourcesfile reads:
! Resource definition file.

! XTerm definitions:
XTerm*font:-misc-fixed-bold-r-normal-15-140-75-75-c-90-iso8859-l
XTerm*scrollBar:true
XTerm* savedlines:2 00

.twmrc

The .twmrc file is a configuration file for Joan's window manager, twm. A window
manager is a special client that controls how windows are moved and resized. In addi-
tion, the window manager defines the root menu shown in Figure 2-2. The .twmrc file
is long, but we can show you the part that definesthe root menu:
menu "rootmenu"

"twm Root Menu" f.title

'Terminal" f.exec "xterm &"
'Clock" f.exec "xclock &"
'Calculator" f.exec "xcalc &"
'Dictionary" f.exec "xwebster &
'Solitaire" f.exec "spider &"
i ii f .nop
'Kill Window" f .destroy
"n f .nop
'Restart twm" f . restart
'Log Out" f .quit

Together, these files define Joan's X user environment. They are defined in addition to the
shell startup files that sheneeds to define her UNIX shell environment.

Now, imagine that you're Joan,new to both UNIX and X, and you're faced with these startup
files. Each file has its own peculiar syntax that she might be able to follow, but will probably
have trouble duplicating. Where did we get that arcanefont name? Why do someof the com-
mands in .xsessionend in ampersands(&) while othersdon't?

The X User Environment 15

2.1.1 The Twilight Zone

One day Joan logs in at a workstation. The X server isn't running on the workstation console,
so Joan tries to start her X sessionby typing X. What she gets is a blank screenwith an "x"
representingher pointer. She is unable to start applications and after several minutes decides
to start over.

After rebooting the machine, Joan learns that she should use the xinit command, not X. When
she does this, she gets a single xterm terminal emulation window with a very small font, and
no window manager,as shown in Figure 2-3.

Figure 2-3. An unconfigured X session

(Unknown to Joan,this has happenedbecausethe .xsessionfile is the one primarily responsi-

ble for configuring Joan's user environment under xdm. Under xinit, she needsan .xinitrc file.
SeeSection 2.4 for more information on starting the X sessionusing xinit.)
Joan tries to start a clock using the xclock command,shown in Figure 2-4.

16 The X Window System Administrator's Guide

ruby:joan 262 xclock

Figure 2-4. Starting a new client

What happensis that the clock appearson top of the xterm window, obscuring her prompt, as
shown in Figure 2-5.

Figure 2-5. xclock window over xterm window

Since there is no window managerrunning, Joan can't move the new xclock window from on
top of the xterm window. She needs to place her pointer on the xterm window and type
RETURNa few times before her prompt peeksout from underneaththe clock window.
What Joan has stumbled onto is X in its unconfigured state.
Joan types "XYZZY". Nothing happens.

The X User Environment 17

 2.2 Components of the X Environment

Joan's adventures are meant to show the world of difference between X in its raw state, and
X when it has been configured. You might think of it as the difference between an unfur-
nished apartmentand a home.
Like someone's home, the X user environment is made up of many components.You can't
just bring in furniture and expect the house to look lived-in; similarly, you can't just start a
window managerand expect the X environment to be complete.
Some users would prefer to configure their own environments. Other users won't have the
slightest idea of where to begin. As an administrator, you have to decide whether you want
to set up an environment with reasonabledefaults for new users, or whether you'd rather just
give usersa bare-bonesenvironment and let them figure it out on their own.
Our opinion is that it's always better to take the time to setup a decent environment for your
users. "Power" users can always rip apart what you set up and start again from scratch; but
users who are just interested in getting their jobs done will appreciate having something
workable to begin with.

One approach to creating a useful default environment is to alter the system-wide files. For
example, if a user has no .twmrc file, they will use the file lusrlliblXllltwmlsystem.twmrc. If a
user has no .xsessionfile, they will use commandsspecified in the lusrlliblXll/xdmlXsession
file. As shipped in the MIT distribution, the defaults in these files are fairly basic. But you
can configure thesedefaults system-wideto better accommodateyour users.
The preferable approach is the "template" approach,as we set up earlier for the user named
Joan. We gave Joan a set of configuration files that had been tried and tested and liked by
other users. The advantageto using templates is that when usersare ready to edit their envi-
ronment, it's much easier if the configuration files are already set up locally.
Either way, the administrator needsto take a strong hand in setting up the user environment.
The administrator is all that stands between a user and the abyss of the default X environ-
ment.

There are an endless number of factors that can influence a user's X environment, but the
simplest user environment (like Joan's) consists of a window manager,a little client customi-
zation, and a startup script to bring it all together.

2.2.1 Window Managers

As we mentioned earlier, window managersare special clients that allow you to move, resize,
and iconify windows. The window manager provided in the X source distribution is twm, the
Tab Window Manager. Window managersare generally started in the user's startup script,
but like other clients, they can be started on the command line as well, as shown in the fol-
lowing figure.

18 The X Window System Administrator's Guide

ruby:joan 262 twm

F/gure 2-6. Starting the window manager

If a window manager were already running, the command would fail with a messageresem-
bling:
twm: another window manager is already running on screen 0?
twm: unable to find any unmanaged screens

The window manager gives each window its own borders and titlebar. By pressing the
pointer on the titlebar (i.e., holding down the first mouse button while the pointer is on the
titlebar), you can move the window. By pressing the icon at the upper right corner of the
titlebar, you can resize the window. By pressing the icon at the upper left corner of the
titlebar, the window is iconified.

Once the window manager is started,you can use it to move windows on the screen.You can
also use it to start new applications on the root menu,as shown in Figure 2-2.
When a new window appears,twm allows you to place the window by displaying an outline
of the window with the upper left corner at your current pointer position. When you pressthe
first mousebutton, the window will be placed at that position.
The behavior of twm can be configured by editing a file called .twmrc in your home directory.
Alternatively, the default behavior of twm on a system can be changed by editing the
system.twmrcfile, usually in the lusrlliblXllltwm directory. For information on how to con-
figure twm, seeeither the twm manual page or The X Window SystemUser's Guide, Standard
Edition (O'Reilly & Associates, 1990).

twm is the only window manager supplied with the MIT X distribution, but there are many
other window managersdistributed by vendors. One of the most popular window managers
is mwm, the Motif Window Manager, mwm is a window manager which implements the
OSF/Motif "look and feel." Another popular window manager is olwm, a window manager
for OPENLOOK. Other window managersare swm (the Solbourne window manager,which
can simulate both olwm and mwm in separate"modes"); gwm (a public domain window man-
ager that usesLISP-like syntax in its configuration, and can simulate mwm); and tvtwm and
olvwm, which are versions of twm and olwm (respectively) that support a "virtual" root win-
dow. A virtual root window is a root window that is larger than the portion visible on your
display. It can be scrolled around to move different sections into view. This simulates having
a much larger display and gives more room to display clients.
See The X Window System User's Guide, Motif Edition (O'Reilly & Associates, 1992) for
more information on mwm and Motif. For more information on olwm and OPEN LOOK, see
the upcoming X Window SystemUser's Guide, OPENLOOKEdition (O'Reilly & Associates,
1993).

The X User Environment 19

 2.2.2 Customizing Clients

There are two ways to customize clients: with command-line options, and with resources.
The use of command-line options to modify the behavior of a program should be familiar to
any UNIX user, but even so, it's worth reviewing a few of the most commonly-used X
options-those for specifying fonts, window size and placement,and colors. This discussion
will also serve to introduce the treatment of resources,which provide a convenient way to set
"global" options.

2.2.2.1 The -fn Command-line Option

For specifying a font, the xterm client provides a -fn command line option. Font namesin X
are a bit unwieldy, but you can use the xlsfonts command to get a list of fonts available for
your X server. For example:
% xlsfonts
-adobe-courier-bold-o-normal-10-100-75-75-m-60-iso8859-l
-adobe-courier-bold-o-normal-Il-80-100-100-m-60-iso8859-l
-adobe-courier-bold-o-normal-12-120-75-75-m-70-iso8859-l

-misc-fixed-bold-r-normal--15-140-75-75-c-90-iso8859-l

(You might also try the xfontsel client, which can be used to display fonts available to your
server.)

See Chapter 6 for a description of each of the fields in a font name. For now, let's use the
fixed font that we showedin the output of xlsfonts. Use the -fn option:
% xterm -fn -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso8859-l &

This command line gives you a window resembling that in Figure 2-7.

2.2.2.2 The -geometry Command-line Option

The -geometry or -g command-line option can be usedto specify two things: where the client
window initially appearsand what size it should initially be. To have an xterm window that's
92 charactersacrossand 40 lines long (insteadof the default 80x24), enter:
ruby:joan % xterm -geometry 92x40 &

To have an xterm window appearat position (324,190) on the screen,enter:

ruby:joan % xterm -geometry +324 + 190 &

You can combine the two requestsinto one argument:

ruby:joan % xterm -geometry 92x40 + 324 + 190 &

You see a window resembling that in Figure 2-8.

20 The X Window System Administrator's Guide

 xferm
rubyljoan
262ty* t-
111U139
ruba:joan
27Zxtern-fn -nisc-fixed-bold-r-i
[2114167
rubaljoan
2820

Figure 2-7. xterm window with new font

The position (0,0) is the upper left corner of the root window. The numbers following the
plus signs (+) signify the offset (in number of pixels) from (0,0). The top left corner of win-
dow is placed at these coordinates when the offset is positive. It is also possible to specify a
negative offset using minus signs (-):
rubyrjoan % xterm -geometry 85x40-50-150 &

The bottom right corner of the window is offset 50 pixels from the right border and 150pix-
els up from the bottom of the screen. Since displays differ in the number of pixels, a window
may be placed differently dependingon the size and resolution of your display. Using a nega-
tive offset will guaranteethat the window is always a certain distance from the right side and
bottom, regardlessof the size. This is handy if you often move from one type of display to
another,as your windows will always remain within the screenborders. In the .xsessionfile
we showed earlier, we had set up some windows to position themselves at particular posi-
tions, using the -g shorthandfor -geometry:
xterm -title Top -g 70x35+1+1 &
xterm -title Bottom -g +1-0 &
xclock -g -0+0 &
xcalc -g -0+298 &
xpostit -sv -g 110x50-0+200 &

The X User Environment 21

 ruby:joan
262twnt,
11}14316
rubaljoan
27Zxter«
(2114339
rubyrjoan
28ZD

Figure 2-8. A window with a specified geometry

" The top xterm window appears at the upper left corner of the screen, and is resized to be
70x35.

" The bottom xterm appearsflush to the bottom left corner of the screen.
" The xclock window appearsflush to the upper right corner of the screen.
" The xcalc and xpostit windows appear flush to the right edge of the screen.The xpostit
control box is also resized a little to look nice.

Without a specified geometry, the placement of windows is controlled by the window man-
ager, appearingat (0,0) if no window manageris running.
The size of the xterm window is given in character widths and heights. For most other X cli-
ents, however, the unit of measurementused for window size is generally the number of pix-
els. Seethe client manpagefor information on what units are usedfor size specification.

22 The X Window System Administrator's Guide

2.2.2.3 Specifying Colors

If you have a color monitor, you might want to use some colors in your display. You can
specify a new foreground and backgroundcolor using the -fg and -bg command-line options.
For example, for a window with a powder blue background and hot pink foreground, enter:
ruby:joan % xterm -bg powderblue -fg hotpink &

Use the showrgb command for a list of colors available on your system for color displays.

On a monochrome display, you can get a black background and white foreground with:
rubyrjoan % xterm -bg black -fg white &

Or get the sameresults by calling xterm with the special-rv option, for reversevideo:
rutyrjoan % xterm -rv &

Either command line will give you a window resembling that in Figure 2-9.

ruby:joan 262 more RELHOTES.TXT

Window System, Version 11, Release 5

Re1ease Notes

HIT X Consortium staff

"or Computer Science

.qht <C> 1991 bn the Me jsetts Institute of Technology.

Permission to use, copy, modify, and distribute this document for any purpose
and without fee is hereby granted, provided that the above copyright notice and
this per miss ion notice appear in all copies, and that the name of MIT not be
rtising or publicity pertaining to this document without specific.

Figure 2-9. An xterm windowin reverse video, decorated by twm

SeeChapter 6 for a complete discussionof color.

The X User Environment 23

2.2.2.4 Using Resources

Command-line options are the quick and dirty way of customizing a client. Before we go on,
however, we should tell you a little about the alternative, using resources.
There are a few disadvantagesto using command-line options. One is that you can end up
with some awfully long command lines. For example, if you want to specify a different
geometry, new font, and different background and foreground colors, your command line
might look like this:
% xterm -fn -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso8859-l \
-geometry 90x40 -bg yellow -fg navyblue &

If you don't want to type this out every time you start up a new xterm window, you could set
up your window manager to run the entire command from your root menu. But the better
solution is to use resources to set up your client preferences.

Resourcesare variables that are used by X clients. They have the advantage of being defin-
able at the systemlevel, at the server level, and at the user level. By defining resources,you
can change the default behavior of clients for your account or for a particular X server. For
example, you can set the following resourcesin a file called .Xresourcesin your home direc-
tory:
XTerm*font: -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso8859-l
XTerm*Background: yellow
XTerm*Foreground: navyblue
XTerm*VTl0 0.geometry: 90x4 0

(The string VT100 used in the geometry specification is the name of a widget used within
xterm.)

To load these resourcesinto the server, where all clients can accessthem, type:
ruby:joan % xrdb -merge .Xresources

After these resources are loaded into the server, all subsequentxterm windows will appear
the way you want them. You can just type:
ruby:joan % xterm &

We have described only a small subset of the things that can be set using resources. A client
may provide resources to redefine almost any variable it uses. For example, in the
.Xresourcesfile we showed earlier, we set the scrollBar resource,and specified the num-
ber of lines to be savedfor scrolling:
XTerm*font: -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso8859-l
XTerm*scrollBar: true
XTerm* savedlines: 200

Resourcesmight be used for anything that the program wants to leave configurable by the
user or administrator. For example, sinftp client may use resourcesto setthe default ftp server
to connect to; the xcalc client usesresourcesto define all of its buttons and the functions they
call; and the xdm client usesresourcesto point to its configuration files. For a listing of the
resources used by a particular client, refer to the manpage provided with that client. For
more information on resources,see Appendix D.

24 The X Window System Administrator's Guide

2.2.3 The Startup Script

The startup script is what brings a user's entire X environment together. If you use xdm to
start your X sessions,this script is called $HOME/.xsession.
If you use xinit, the script is
called $HOMEI.xinitrc * We'll show the simple startup script that we used earlier:
#!/bin/sh

# Add /usr/local/bin to the path for this script:

PATH=$PATH:/usr/local/bin
export PATH

# Set up a pattern for the root window:

xsetroot -bitmap /usr/include/Xll/bitmaps/dimplel

# Merge in user resources:

xrdb -merge $HOME/.Xresources

# Start some applications:

xterm -title Top -g 70x35+1+1 &
xterm -title Bottom -g +1-0 &
xclock -g -0+0 &
xcalc -g -0+298 &
xpostit -sv -g 110x50-0+200 &

# Start a window manager in the foreground:

twm

The first thing that this startup script does is set the path to be used for commandsfor that
script. By default, :lbin:lusrlbin:lusrlbinlXll :lusrlucb is used as the search path for the
startup shell. Since the xpostit command resides in /usr/local/bin, it needs to be called with
its full pathname, or /usr/local/bin needs to be appendedto the searchpath. This path is then
exported, so that it will also be usedby other clients such as twm.
The startup script usesxsetroot to give the user a nicer background than the default root win-
dow background.

Next, the startup script calls the xrdb client. It is this command that reads the resources
defined in the .Xresources file. The xrdb client loads resources directly into the X server.
There are alternate ways of reading resources(as described in Section D. 1.2),but if you load
the resources directly into the server, you guarantee that all clients displaying to that server
will be able to accessthem, xrdb should be run before any applications are run, since you
want to make sure that the resources are loaded before you start any applications that use
them; and it should be called in the foreground, to guarantee that the resources are fully
loadedbefore the script continues.
The applications are then started. We describedhow the -g options are being used in Section
2.2.2.2.Note that each of thesecommand lines are placed in the background.
Finally, the twm window manager is started. When twm starts up, it is configured by the
.twmrc file.

' See Section 2.4 for more information on using xinit. See Chapter 3 for more information on using xdm.

The X User Environment 25

2.2.3.1 The Foreground Process

As shown in the sample startup script, clients such as xrdb and xsetroot are not run in the
background, xrdb and xsetroot are non-interactive clients that exit as soon as they are com-
pleted.

On the other hand, clients like xterm and xcalc need to be put in the background, or the script
will hang until they are completed (or killed). What the user will see is that the top xterm
window appears, but nothing else; after the user exits xterm, the bottom xterm window
appears;the secondxterm window has to be killed before the xclock window pops up; and so
on.

There is one exception: the last interactive client is always left in the foreground. Otherwise
(like any shell script), the startup script exits immediately, and the X server resets(killing all
clients). What the user will see is that all windows appear and then instantly disappear.

The last interactive client therefore keeps the X session alive. When it is exited (or killed),
the entire X sessionexits as well. For that reason,the last process is also frequently called
the controlling process.
The sample script makes the twm window manager the foreground process.The root menu
option to exit twm is labeled "Log Out" to make it clear that exiting twm will log you out of
your X session.In real life, you can make any interactive client your foreground process.
In general, users make their foreground process either an xterm client or their window man-
ager. If you use the window manager, exiting the window manager exits the entire X session,
which is an intuitive way to exit but meansthat you can't change window managerswithout
editing your startup file and restarting X. If you use an xterm window, you may want to run
the window with the -iconic option, in the hope that if the window is iconified, then the user
is less likely to exit accidentally. Users with consolexterm -C or xconsole clients often use
the console window as the controlling process.

Another possibility is to use the built-in shell command wait at the end of the startup script,
in which caseyou will have to exit each X client individually before your X sessionexits.
If you use an xterm window for your controlling process,beware of the "autologout" feature
available for some shells. With the "autologout" feature, you can set it up so that your shell
is killed when it is idle for a certain amount of time, e.g., 60 minutes. You can be working
frantically in another X window, but if you have autologout set for your controlling
xterm shell, then your whole X session will be killed after 60 minutes of idle time in the con-
trolling shell.

26 The X Window System Administrator's Guide

 2.3 The Shell Environment

Now we've talked a little about the X environment, we have to discuss how it relates to the
UNIX shell. Although the shell is external to the X environment, X clients running on UNIX
systemsnecessarily depend on the shell being set up properly. This meansmaking sure that
environment variables are set up properly and that the searchpath is correct. For remote cli-
ents, you have to deal with the shell environment on the remote machine as well.

2.3.1 Setting the DISPLAY Variable

The most important shell environment variable for X clients is DISPLAY. When a user logs
in at an X terminal, the DISPLAY environment variable in each xterm window is set to her X
terminal's hostname followed by : 0 . 0.
ruby:joan % echo $DISPLAY
ncdl5.ora.con:0.0

When the same user logs in at the console of the workstation named sapphire, the DISPLAY
environment variable is defined as just : 0 . 0:
sapphire:joan % echo $DISPLAY
:0.0

(Before XI1 Release5, the DISPLAYvariable might appearas unix: 0 . 0.)

The DISPLAY environment variable is used by all X clients to determine what X server to
display on. Since any X client can connect to any X server that allows it, all X clients need
to know what display to connect to upon startup. If DISPLAY is not properly set, the client
cannot execute:

sapphire: joan % setenv DISPLAY foo:0

sapphire: joan % xterm
Error: Can't Open display

You can override the value of DISPLAY by using the -display command-line option. For
example:
sapphire:joan % xterm -display sapphire:0.0 &

The first part of the display name (up to and including the colon) identifies the type of con-
nection to use and the host that the server is running on. The secondpart (in most cases,the
string 0.0) identifies a server number and an optional screen number. In most cases,the
server and screen numbers will both be 0. You can actually omit the screennumber name if
the default (screen 0) is correct.

Note that we used both ": 0 . 0" and "sapphire: 0 . 0" to accessthe local console display
of the workstation named sapphire. Although both these nameswill work, they imply differ-
ent ways of connecting to the X server.

The X User Environment 27

 1. The ":" character without an initial hostname specifies that the client should connect
using UNIX domain sockets(IPC).
Instead of specifying : 0.0, you can also prepend the word "unix" for an IPC con-
nection:

sapphire:joan % setenv DISPLAY unix:0.0

(This is used in pre-R5 releasesof XI1.)

Since processescan communicate via IPC only if they are running on the samehost, you
can use a leading colon or the unix keyword in a display name only if both the client
and server are running on the samehost-that is, for local clients displaying to the local
console display of a workstation.
2. Using the hostname followed by a colon (e.g., sapphire:) specifies that the client
should connect using Internet domain sockets (TCP/IP).You can use TCP/IPconnections
for displaying clients on any X serveron the TCP/IPnetwork, as long as the client has per-
mission to accessthat server (see Section 2.3.4 for information on running remote cli-
ents). You can also use the hostname form for displaying clients on the local server,
although many people argue that it's preferable to use unix: 0.0 for any local clients.
(It's faster,and there's no danger of a misconfigured name servergetting in the way).
3. There is one other way of connecting: on a DECnetnetwork, the syntax is the sameas for
TCP/IPexcept that two colons are used instead of one. To connect to an X serverrunning
on a host named oravax on a DECnetnetwork, you might use the string oravax: : 0 . 0.

2.3.1.1 Complications with Display Names

Occasionally, especially when testing a new server, you may find that you can't open a par-
ticular display. When confronted with such a situation, we recommend trying the following:
" Make sure that you are using the proper name of the display, especially if you are running
a client from a foreign host. A common mistake is to use : 0 or unix: 0, forgetting that
different hostshave different ideas of what these display namesrefer to.
" Make sure that TCP/IPis properly configured by confirming that other connectionswork,
using (for example) rlogin or telnet.
If you suspectthe problem is with your name server, substitute the IP addressof the dis-
play for the hostname:
ruby:joan % xterm -display 140.186.65.35:0

" Make sure that accesscontrol isn't the problem by temporarily allowing accessto all
hosts on the server machine. (Rememberto undo this after the experiment!)
sapphire: joan % xhost +

If this turns out to be the problem, see Chapter 4 for more information on how to config-
ure serveraccesscontrol more robustly.

28 The X Window System Administrator's Guide

 " Some versions of TCP/IP,particularly on PCs, restrict the number of allowed connections.
Find out whether the machine running the server program is restricted to a certain number
of TCP/IP connections and increase it as needed. (How you actually do this is dependent
on the TCP/IP vendor.)

Note that like all other environment variables set in your shell environment, the DISPLAY
environment variable will propagate to all processesyou start from that shell.
When you run clients from remote machines, some additional problems with the DISPLAY
environment variable need to be addressed. See Section 2.3.4 for more information on run-
ning remote clients.

2.3.2 Redefining the Search Path

The command search path needs to include the directories containing X executables. This
searchpath should live in the user's startup shell script (.cshrc or .profile). Assuming that the
X executablesare in lusrlbinlXll and /usr/local/bin/Xll, here's a simple adaptedentry for a
.profile file (Bourne shell):
PATH=/usr/ucb:/bin:/usr/bin:/usr/bin/Xll:/usr/local/bin/Xll:.
export PATH

And here's one for a .cshrc file (C shell):

set path = (/usr/ucb /bin /usr/bin /usr/bin/Xll /usr/local/bin/Xll .)

(For security reasons, you may want to omit the current directory (.) from your path.)

If the path is not set properly, you will get the notorious "Command not found." error
message for all X clients.

Unless specified otherwise, the .xsession startup script has the search path set to
:/bin:/usr/bin:/usr/bin/Xll:/usr/ucb. If you run clients in your startup script that reside in a
different directory, you may need to reset the search path within the startup script. You may
need to do this if you generally use the C shell, but your .xsessionis a Bourne shell script.
For example:
#!/bin/sh
PATH=$PATH:/usr/local/bin/Xll:$HCME/bin
export PATH

Alternatively, you can write your .xsessionas a C shell script, in which caseit will automati-
cally run your .cshrc file and inherit the searchpath set in that file.

The X User Environment 29

2.3.2.1 Setting the Search Path for OpenWindows Support

If you are running OpenWindows, you need to add the following directories to your search
path along with your vanilla X11 binary directories:
set path = ($path /usr/openwin/{bin,demo} )

(In OpenWindows 3.0, the Ibinlxview directory is now linked to bin.)

In addition, you need to set the sharedlibrary path to lusrlopenwinllib:
setenv LD_LIBRARY_PATH /usr/openwin/lib:/usr/lib

If the OpenWindows distribution is elsewhere on your system, you can set the
OPENWINHOMEenvironment variable and use it in place of /usr/openwin. For example, if
the OpenWindows distribution is in lusrllocal/'openwin, C shell userscan enter in their .cshrc
files:

setenv OPENWINHOME /usr/local/openwin

set path = ($path $OPENWINHOME/{bin,demo} )
setenv LD_LIBRARY_PATH $OPENWINHOME/lib:/usr/lib

In Bourne shell syntax, this might read:

OPENWINHOME=/usr/local/openwin
PATH=$PATH: $OPENWINHOME/bin: $OPENWINHOME/demo
LD_LIBRARY_PATH=$OPENWINHOME/lib:/usr/lib
export OPENWINHOME PATH LD_LIBRARY_PATH

2.3.2.2 Setting the Search Path for Mixed Environments

If you are running multiple releasesof XI1 on your system,you needto set your searchpath
appropriately according to which executablesyou want to run. One situation in which you
might want to run multiple releasesis if you are testing a new releaseof XI1 before setting it
loose on your users. For example, supposethat you have X11R4 installed and running in
lusrlliblXll and lusrlbinlXll, and have just compiled and installed X11R5 into
I usr1X1lR5llib and I usr1X1lR5/bin. For testing your new environment, enter the
I usr1X1lR5lbin directory into your command searchpath before lusrlbinlXll:
set path = ( /usr/XHR5/bin $path )

On SunOS,you also needto enter lusrlXllRSIlib into your LD_LIBRARY_PATH:

setenv LD_LIBRARY_PATH /usr/XHR5/lib

Another possibility is to set the LD_LIBRARY_PATH environment variable for each com-
mand:

% (setenv LD_LIBRARY_PATH /usr/XHR5/lib ; /usr/XllR5/bin/xterm)&

30 The X Window System Administrator's Guide

 2.3.3 xterm Issues

The xterm client, which starts up a terminal shell, has its own particular issues,xterm has to
have its termcap or terminfo entries installed, and since xterm windows can be resized, it
needsto be able to adjust thoseentries dynamically for different dimensions.

2.3.3.1 xterm and Terminal Emulation

Among other common functions, shell startup scripts such as .login and .profile generally
deal with setting the terminal type for that shell. This might be as simple as setting the TERM
environment variable, or something more elaborate using tset.
Setting the terminal type, however, is not required for xterm terminal windows. The xterm
client has its own way of dealing with terminal types. Several terminal entries work with
standard-sized(80x24) xterm windows, including "xterm," "vt!02," "vtlOO," and "ansi."
The xterm client automatically searchesthe terminal databasefor theseentries (in order) and
setsthe TERM environment variable according to which entry it finds first.
Since xterm takes care of setting terminal emulations by itself, you may want to remove any
lines in startup files that set the terminal type, or have them default to "xterm."
There are two types of terminal databases available on UNIX systems: termcap. usually
associatedwith BSD-basedsystems,and terminfo, associatedwith System V-based systems.
The xterm source directory contains files called termcap and terminfo that contain the
termcap and terminfo definitions for xterm. The termcap file tor xterm should be entered as
one of the first entries in your letc/termcap file. The terminfo file is meant to be compiled
with tic, the Terminfo Compiler. For more information on termcap and terminfo, see the
Nutshell Handbook, termcap and terminfo (O'Reilly & Associates, 1991).
Your vendor may supply its own version of xterm with its own terminal emulation and other
enhancements(e.g., hpterm, aixterm, or scoterm). Seeyour vendor's documentation for more
details.

2.3.3.2 The resize Client

When the xterm client is called, it not only sets the TERM environment variable, but it also
adjusts the terminal definition for the size of the window that is being created. The size of
xterm windows, however, can be changed later on by using the window manager. If the win-
dow is resized, then the user's shell may need to be passedthe new size information as well,
or programs that use termcap and terminfo won't work correctly. The resize client is pro-
vided for redefining the number of lines and columns for the terminal databasethat is used in
an xterm window. Note that resize cannot be used for terminal emulators other than xterm,
since it dependson xterm's escapesequences.
Some systemscan send a "window size changed" signal (SIGWINCH)to programs and do not
require resize to be run for a resized xterm window. We recommend using resize only if ter-
minal-based programs start to have problems with your window size. A typical terminal-
basedprogram that is having problems with the window size is shown in Figure 2-10.

The X User Environment 31

 xterm

OMMSXConsortium: I makefile,^ 1.105 91/07/27 14:13:23 ruis Exp $

#define IHaveSubdirs
^define PassCDebugFlags

WORLDOPTS
= -k
CHECKFNSRC
= $<UTILSRC)/checkfn
CHECKFN= $<CHECKFNSRC Vcheckfn

#if BuildServer
SERVERDIRSTOMflKE = server rgb
tendif
SUEDIRS = config include lib extensions fonts $<SERVERDIRSTOMAKE>
\
clients demos util man
LNINSTfiLLDIRS = $<LIBSRC) $(EXTENSIONSRC)

MakeSubdirs($(SUBDIRS»

MakeLintSubdirs<$(LNINSTALLDIRS),instal1.In,instal1.In)

MakeLintSubdirs($(LNINSTfiLLDIRS)external.In,1intlib>

[makefile" [Read only] 107 lines, 2918 characters

Figure 2-10. vi using only part of a window

The resize client is typically used immediately after the dimensions of an xterm window are
changed.A peculiarity of the resize client is that it does not accessthe shell itself, but simply
returns the shell commandsthat would be needed;to have those commandsread by the shell,
you have to either save its output in a file and source it in with the "." command (Bourne
shell) or source (C shell) commands,or call it using the shell command eval. For example,
after resizing a window you would type in that shell:
% eval * resize*

When you call the resize command under a termcap system, it producesthe commandsfor
resetting the TERMCAPenvironment variable with the li# and con capabilities reflecting the
current dimensions.When you call the resize command under a terminfo system,it produces
the commandsfor resetting the LINESand COLUMNSenvironment variables.

32 The X Window System Administrator's Guide

 The resize command consults the value of your SHELL environment variable and generates
the commands for setting variables within that shell. If you are using a non-standard shell,
resize may still recognize your shell; as of R5, resize recognizestcshjcsh, ksh, bash, andjsh.
But if resize does not recognize your shell, try using the -c or -u options to force resize to
use C Shell or Bourne Shell syntax (respectively), depending on which syntax is appropriate
for your shell.

2.3.3.3 xterm and the Login Shell (C Shell)

Most people who use the C shell know that the .cshrc file is read for every csh command run,
and the .login file is read only once, at the beginning of each "login shell." One thing that X
does is to effectively redefine the meaning of the "login shell."
Before X, you could assume that a user had a single interactive shell per login. Since the
.login file would therefore be read only once, at the beginning of the login session,you could
use it as a "batch" file to run somedaily commands.For example, you might have it show the
"messageof the day" and start mail for you first thing in the morning:
cat /etc/motd
mail

Since X gives you the ability to run multiple xterm windows, however, the usageof the .login
file becomes more confused. You probably don't want to read your mail and see the "mes-
sageof the day" every time you call up a new xterm window. It makes more sensefor these
functions to be taken up by your X startup script, and to run X clients rather than text-based
applications. For example, if you log in via xdm, your .xsessionmight contain the lines:
# Shew the message of the day:
xmessage -file /etc/motd &

# Start a mail application:

zmail -gui &

Here, we use the contrib client xmessage to show the message of the day, and we call up an
X-based commercial mail application, zmail.
What does that leave for terminal emulator windows like xterml Well, by default, xterm
shells are not login shells-that is, xterm shells don't run .login, but just the shell startup file
.cshrc. You can call up a login shell xterm by starting xterm clients with the -Is option.
(Alternatively, you can set up all xterm?,to run login shells by setting the XTerm*login-
Shell resource to true.)

Whether you want to set up xterm as login shells dependson what you use .login for. How-
ever, you might want to start thinking of the .login file as the startup file for ASCII-based user
sessionsonly. Some of the functions of the .login script don't make sensefor xterm shells
(such as setting the terminal type, which xterm is smart enough to do on its own). But those
functions are still useful for when you log in at an ASCII terminal, which you undoubtedly
still do on occasion (for example, when dialing in on a modem line).
The .cshrc file therefore takes on a lot more responsibility for your shell environment, since it
needs to make the xterm shell environment complete on its own. Since it's also used for C

The X User Environment 33

 shell scripts, you can write it so it tests for a prompt and provides interactive-shell startup
commands for interactive shells only:
# Make default file mode -rw-rw-r-.
umask 002

set path=(/usr/local/bin /usr/ucb /usr/bin /usr/bin/Xll .)

# Fix "dirs" and "$cwd" not to be fooled by symbolic links:
set hardpaths

# ALIASES AND OTHER INTERACTIVE COMMANDS GO BETWEEN HERE AND endif:

if ($Pprompt) then
set history=50 savehist=25
set host=vhostname"
set mail=(300 /usr/spool/mail/$user)
set prompt="${host}:$user \!% "
alias h history
alias Is "Is -F"
alias rm "rm -i"
stty erase /Ah'
setenv PRINTER dodo_ps
endif

In this example, the part between "if ($?prompt) " and "endif" are only executed for
the primary interactive shell.
Note that if you use xinit to start your X session,then your .login file is executed when you
first log in prior to starting the X server. If you use xdm to start your X session,the .login file
is never executedat all unlessyou run xterm with the -Is option.

2.3.4 Starting Remote Clients

One of the advantagesof a window system like X is that you can run applications remotely
and view them on the local display. You can try this easily enough by just doing a rlogin to
the remote host, setting the DISPLAY environment variable, and starting up a client. In the
following example, we start up a new xterm client running on the host ruby:
sapphire: j oan % rlogin ruby
Password:
Last login: Tue May 12 16:27:23 from sapphire.ora.com
SunOS Release 4.1.2 (RUBY+COALM+PPP) #1: Tue Mar 3 23:29:52 EST 1992
You have mail.
TERM = (vtlOO) xterm

ruby:joan % setenv DISPLAY sapphire:0

ruby:joan % xterm &

(You must, of course,have an account on the remote system.)

The first thing that might go wrong is that you may run into server accesscontrol. If you see
the following error:
Xlib: connection to "sapphire:0" refused by server
Xlib: Client is not authorized to connect to Server
Error: Can't open display: sapphire:0

34 The X Window System Administrator's Guide

 you can probably fix it by typing "xhost +ruby" in a sapphire window, and running the
command again on ruby.* Or, if you use user-basedaccesscontrol on the local host, use the
xauth command to propagate the accesscode to the remote machine. SeeChapter 4 for more
information on server access control.

(Other possible problems may be with your host database,with Yellow Pages(NIS), or with
the Domain Name Service. See Section 2.3.1.1 for more information on conflicts with dis-
play names.)

Once you have networking and accesscontrol issues solved, you should be able to display
clients from the remote machine. The next issueis how to run remote clients easily.

2.3.4.1 Starting a Remote Client with rsh

The preferable way to start a remote client is the sameway you'd start any remote command:
using the rsh command:
sapphire: joan % rsh ruby -n xterm -display sapphire: 0

There are a few issues to be ironed out first, though.

In order to run rsh successfully, you need to make sure that you have permission to run
remote shells on the remote machine. This means that the local machine must be listed either
in the remote machine's tetdhosts.eqmv file, or in your personal $HOME/.rhostsfile on the
remote machine. For example, an .rhosts file might read:
sapphire.ora.com
harry.ora.com

If the host is properly set up on the remote machine, then rsh will execute properly and rlogin
will no longer ask for a password when you try to connect to the remote machine. If it is not
set up properly, then rlogin will prompt for a password,and rsh will fail with the message
"Permission denied."

Using .rhosts or letclhosts.equiv for this purpose might be considered a breach of security,
since it meansif someonebreaksinto your account on one machine, they can break into your
account on all other machines as well. Clearly, you want to be careful what hosts you list in
.rhosts. For that reason,it's better to use the fully qualified domain name (i.e., harry.ora.com
instead of just harry).
There are a few more rules:

" The .rhosts file will be ignored if it is publically writable, for security reasons.Make sure
that the .rhosts file is writable only by you.
" Make sure you are running the correct rsh command. Some systemshave a "restricted"
shell, also named rsh. If you get the following error:
ruby: ruby: No such file or directory

*The security-conscious may prefer to use the fully qualified domain name on the xhost command line (such as
xhost +ruby .ora. com).

The X User Environment 35

 or:

ruby: ruby: cannot open

where ruby is the name of the system that you wanted to run the remote shell on, the
problem is probably that are using the wrong rsh command. Use the which or whereis
command to track down which rsh you are using:
sapphire:joan % which rsh
/bin/rsh
sapphire:joan % echo $path
/bin /usr/bin /usr/bin/Xll /usr/bsd

On some System V-denved systems such as IRIX, the restricted shell rsh might live in
Ibin, while the remote shell rsh (the one you want) residesin /usr/bsd. Ibin often shows
up in searchpaths earlier than /usr/bsd, so on those systemsyou need to explicitly rede-
fine your path so that /usr/bsd is searchedbefore /bin.
" You may need to use the -n option to rsh to avoid a "Stopped" error messageon some
machines.

" You need to be sure that the directory containing X binaries is defined in your searchpath
in either .cshrc or .profile on the remote system.
" If you are using host-basedaccesscontrol, you needto execute the xhost client to extend
access to the remote host before the rsh command is run. Otherwise, clients from the
remote host will not have permission to accessyour display. If you are using user-based
access control, you may need to run the xauth command to copy your access code to the
remote machine. See Chapter 4 for more information on server access control.

" You have to use the -display option in calling a remote shell, or the "Can't Open
display" error will be returned. (Alternatively, you can have your DISPLAY environ-
ment variable hard-coded into your .cshrc or .profile on the remote machine, but this is a
Very Bad Idea.) SeeSection 2.3.1 for more information on setting your display.
" Be careful not to use unix: 0 . 0 or : 0 . 0 as the display name! Otherwise, the client
will display the window on the local display of the remote host. If this succeeds,the user
on that display could either becomevery annoyed,or could take advantageof the sudden
access to your account to read personal files and send nasty mail to your boss. You would
have no warning; all you would know is that your window didn't appear. (See Section
2.3.1 for more information on the DISPLAY environment variable.)

A common situation is to start rsh commands as follows:

sapphire: joan % rsh ruby -n xterm -display $DISPLAY

This works great if your DISPLAYvariable is set to something like sapphire: 0 . 0, but
if it's set to unix: 0 . 0 or : 0 . 0 (as is the default for X sessionsbegun on the console
display), then the wrong display name will be sentto the remote machine.

The X11R5 distribution contains a shell script called xrsh in the contribi'clients area. This
script sets the DISPLAY variable for the remote client and handles authentication according
to the value of an XRSH_AUTH_TYPEenvironment variable. See the manpage on xrsh for
more information.

36 The X Window System Administrator's Guide

2.4 Startup Methods

The X Display Manager,xdm, is the method of choice for starting your X session.The main
reason for this is that xdm is the only elegant way of starting an X sessionon an X terminal or
other remote "passive" X server. However, for local X servers,you can use the xinit or startx
command to start both the X server and your X session in a single step. If you are running a
vendor-configured version of X, there might also be another command for starting the X
server,such as open-winfor Sun OpenWindows; see your vendor's documentation for details.
On an X server controlled by xdm, the X server is always running, and usersstart their indi-
vidual X sessionsby logging in via a login box window.

emerald

Login:
Password:

Figure 2-11. Logging in with xdm

When you log in, your window manager and other X clients are automatically started, as
specified in your .xsessionstartup script. Chapter 3 discussesxdm in detail.
On a local console display server that does not already have the X serverrunning (i.e., is not
controlled by xdm), you log in as usual on the console (using getty) and type xinit to start
both the X server and the X clients specified in your .xinitrc script.

The X User Environment 37

 login: Imui
Password:
Lastlogin: WedMay6 14:1:36from ncd10.ora.com
SunOSRelease 4.1.2(RUBY+COALM+PPP) #1: TUEEST1992
lmui@rubble% xinit

Figure 2-12. Starting the X server with xinit

2.4.1 xinit and startx

The xinit program first starts up the X server for the local display. By default, it startsthe X
server by running the program called lusrlbinlXlllX. X is usually a link to another server
program, for example, Xsun on a Sun workstation.
You can override the server command by entering another command in a file called
$HOMEI.xserverrc.For example, it could contain:
/usr/bin/Xl1/XsunMono

You may want to set up a new command in $HOMEi.xserverrcif you are testing a new server
for your display, or if you prefer to start up your serverwith particular command-line options.
If you want to test an option to the X server, follow the xinit command with two dash charac-
ters (- -) and it will passany following command-line options onto the server. For example:
% xinit -- -dev /dev/cgthreeO

After starting the server, xinit looks for a shell script called $HOMEI.xinitrc. As we saw in
Section 2.1.1, if $HOMEI.xinitrc does not exist, a single xterm window is sent to the local dis-
play to get you started.

The startx script is a front end to xinit provided in XI1R4 and XI1R5. Like xinit, it looks for
an .xinitrc file in your home directory; however, if you don't have an .xinitrc, it then usesa
system-wide default file in lusr/lib/Xll/xinit called xinitrc. This file can also be used as a
template for .xinitrc files, startx also uses a file called xserverrc in the same directory for
userswho don't have an .xserverrc file in their home directory.

38 The X Window System Administrator's Guide

2.4.2 Differences Between .xinitrc and .xsession

All of the rules about configuring .xinitrc files also apply to .xsessionfiles. For that reason,
many users simply link their .xinitrc files to their .xsession files. However, there are three
points to consider:
1. The .xsession file is generally a shell script, but it can actually be any executable file,
such as a session manager or desktop manager, .xinitrc must be a Bourne shell script.

2. The .xsessionfile must be an executable file. If you get bounced back to your xdm login
box, you might have to do the following:
% chmod +x .xsession

The .xinitrc file does not have to be executable.

3. The .xsessionscript does not inherit the user's login shell environment. The .xinitrc script
inherits the environment from the shell from which it was run.

2.5 Related Documentation

For more information, see the X Window System User's Guide, by Valerie Quercia and Tim
O'Reilly, published by O'Reilly & Associates,Inc.
The following X manual pages may be of interest: X, xrdb, xinit, xset, xterm, twm, mwm,
olwm, xlsfonts, showrgb, and resize.
The following UNIX manual pagesmay be of interest: rsh, csh, and sh.

The X User Environment 39

 3

The X Display Manager

The X Display Manager provides a way for users to log on and start initial cli-
ents, regardless of which X server they use. This chapter shows how to get
xdm going and how to configure it to the needs of your site.

In This Chapter:
xdm Concepts 44
xdm Configuration Files 46
xdm the Easy Way 48
Troubleshooting xdm 49
Customizing xdm 51
The Master Configuration File (xdm-config) 51
Listing X Servers (the Xservers File) 53
Xservers Syntax 53
xdm Host Access Control: the Xaccess File (R5 Only) 55
Direct and Broadcast Access 56
Indirect Access and the Chooser 57

Using Macros 59
Advantages and Disadvantages of the Chooser 59
The Xresources File 60
Configuring the Login Box 60
The xconsole Client 62
Starting Up Individual X Sessions (the Xsession File) 63
No Home Directory? (R5) 64
Display Classes 65
Testing Your xdm Setup 66
Resetting the Keyboard 67
Restarting xdm Using xdm-pid (R4 and Later) 68
Rereading xdm Configuration Files (R3) 68
Permanent Installation of xdm 69
Related Documentation . ..70
 3
The X Display Manager

The X Display Manager,xdm, runs as a daemon on a host machine. It provides a way for
usersto log on and start initial clients, regardlessof what X serverthey use.
Not all sites use xdm to control X sessions. Many workstation users still prefer to log on as
usual on the console and use the xinit program to start the X server and any preferred clients.
xinit, however, is considered obsolete by the X Consortium, with all new functionality being
built into xdm. And on a site that includes X terminals, xdm is an essential tool for providing
a standard way for users to log on across the network.

xdm also provides a way for administrators to configure environments system-wide. So if you
don't already use xdm to control X sessions for users on your site, we encourage you to give
it a try.

xdm and Vendor Environments

If you're running a vendor-distributed version of X that's greatly modified from the

MIT version, your mileage may vary with this chapter. For example, the OpenWindows
2.x server doesn't work very well with xdm at all. The OpenWindows 3..v distribution,
meanwhile, supplies its own version of xdm which is somewhat modified from the ver-
sion documented here.

SCO Open Desktop has its own version of xdm, called scologin, which must be used for
all logins, scologin is enhancedin that it has SCO's sessionmanagerscosessionbuilt-in
as the controlling process for the X session,and it checks for expired passwords,scolo-
gin also provides a front end (Ietclscologin) to facilitate some administrative responsi-
bilities.

In addition, many vendor-supplied X environments already have xdm pre-configured

when X is installed.

The X Display Manager 43

3.1 xdm Concepts

The xdm program is simply an X client that managesthe first and last points of connection,
control, and coordination of the user session. If you need a conceptual feel for what the X
Display Manager is, think of xdm as working for network-connected X serversthe way init,
getty, and login work for serial-connectedASCII terminals. This is only a loose comparison,
but it will serveour purposesin conveying the general function of xdm.
Like init, xdm keepstrack of which X servers are available to be connected. When init has
determined that an ASCII terminal is available to be managed,it spawns the getty program,
which puts up a login prompt. Similarly, when xdm is given managementof an X server, it
sendsa login box to the serverdisplay.
When a user types a name and passwordon a serial ASCII terminal, that information is sentto
the login program, which authenticatesthe passwordand then starts up whatever program is
specified in the user's /etc/passwd,almost always an interactive shell. When the shell begins,
user-configurable batch files are executed, $HOMEi'.profile for the Bourne/Korn shell or
$HOMEI.cshrcand $HOMEI.login for the C shell. The user is then deposited in the selected
shell environment, ready to run UNIX commands.

For a user who logs in with an xdm login box, the name and password are also authenticated,
using the same mechanism as the login program. However, this is where the functions of
login and xdm diverge. As shown in Figure 3-1, instead of running an interactive shell, xdm
runs a seriesof shell scripts. Thesescripts normally start all your desired X clients, including

xlogin box

login authentic?

exec(Xresetscript) exec(Xstartupscript)

exec Xsession

#!/bin/sh
#Load resources
xrdb -merge $HOME/.Xresources
#start window manager
twm&
#lnitial xterm
xterm -name login

exec $HOME/.xsession

Figure 3-1. xdm flow chart

44 The X Window System Administrator's Guide

one or more terminal emulators, each of which will contain an interactive shell. In the
default xdm configuration, Xsessionis one of the shell scripts that are executed.Xsessionthen
calls another script called $HOMEI.xsession(if it exists).
When a user logs out on a character-basedterminal, control of the terminal returns to getty,
sending another login prompt to the terminal. Consistent with that model, when a user logs
out of an X session (i.e., when the "controlling" process of the X session has been ter-
minated), xdm closes all connections and resets the terminal to a "ready for log on" state,dis-
playing a new login box, ready for another user session.
As you can see,xdm is a very ambitious program. It can be configured to control logins on
multiple X servers connected to the same machine, creating customized sessions,and offer-
ing somebasic network security features.
The conclusion is that xdm, when set up properly, enables users to walk up to a display and
log in by typing their usernamesand passwords,the same as they would on an ASCII termi-
nal, xdm then runs their startup scripts automatically, setting up customized environments
and enabling usersto begin productive work immediately. When usersfinish their X sessions,
xdm resets each display for the next user. With the X session startup process incorporated
into the login process, users need to know relatively little about XI1 to start work-
ing-given, of course, that xdm and users' individual environments are configured appropri-
ately.

History of xdm and XDMCP

xdm was introduced with XI1R3, to support the X terminals that were just coming to the
market. That first version of xdm had severalproblems, which were solved in XI1R4 by
the introduction of the XDM Control Protocol (XDMCP).

The most urgent problem that XDMCP addressedwas the problem of X terminals that are
turned off and on again. Prior to XDMCP,the only way xdm knew to control an X termi-
nal was to look for its entry in the Xservers file (see Section 3.5.2 for more information).
Since Xservers is consulted only when xdm is first started,this causedproblems when X
terminals were turned off temporarily, or when new X terminals were attached. It meant
that every time a user turned an X terminal off and on, the systemadministrator needed
to senda SIGHUP to xdm. XDMCP provides a solution to this problem.
XDMCP, introduced in X11R4, is a protocol shared by the xdm client and X servers
throughout the network. Using XDMCP, the X server has the responsibility of actively
requestingan xdm connection from the host. If an X serverusesXDMCP,therefore, it no
longer requires an entry in Xservers since the host no longer has the burden of initiating
the connection.

Almost all X terminals sold today are XDMCP-compatible. R4 and R5 servers running
on local console displays are also XDMCP-compatible, but XDMCP queries are not
enabledby default.

The X Display Manager 45

3.2 xdm Configuration Files

xdm is configured through a set of editable ASCII files for someof the mechanismsyou would
expect-a list of servers to be explicitly controlled by xdm, resources to be used by xdm,
error messages,whether to use security, etc.-but it also provides ASCII files for setting up
an initial default sessionand setting resourcesto be loaded by the server itself. The files used
for xdm configuration in lusrlliblXll/xdm are listed here (and shown in Figure 3-2), to be dis-
cussedin detail later in the chapter:
xdm-config Resourcesspecified for xdm. Note that the location of all other files listed below
can be redefined with resources specified in xdm-config. (The location of the
xdm-config file itself can be reassignedusing the -config option to xdm when it is
started.)

Xservers A list of servers to be explicitly managed by xdm. The local display server
usually needsto be listed here.
Xsession The initial startup script used by each individual X session.
Xresources Resourcesto be loaded via xrdb by serversmanagedby xdm.
xdm-pid A file containing the processID of xdm. (This file is not designed to be edited by
administrators,but is for informational purposesonly.) (XI1R4 and later only.)
xdm-errors The error log file for xdm. (This file is not designed to be edited by administra-
tors, but is for informational purposesonly.)

Figure 3-2. Default xdm configuration files

46 The X Window System Administrator's Guide

Xaccess A file for configuring accesscontrol for XDMCP, specifying different behavior
according to the sort of query used. This configuration file is new to XI1R5.
GiveConsole
A shell script that changesthe ownership of the console to the user. This file is
new to XI1R5. See Section 4.6.2 for information on how the GiveConsole script
is used.

TakeConsole
A shell script that changesthe ownership of the console back to root. This file is
new to XI1R5. See Section 4.6.2 for information on how the TakeConsolescript
is used.

XsetupJ) A shell script used for display setup specific to the local console server.This file
is new to XI1R5.

In users' home directories, the following files are used by xdm in its default configuration:
$HOMEI.xsession
User-specific startup script executed by the systemwideXsessionscript.
$HOMEI.Xresources
User-specific resourcesread by the systemwide Xsession script if $HOMEI.xses-
sion does not exist. (If $HOMEI.xsessiondoes exist, then the .xsessionscript is
responsible for loading user-specific resources from .Xresources or any other
resourcefile.) SeeAppendix D for information on setting resources.
$HOMEI.xsession-errors
Errors specific to a user's X session (R5 only). This file is not designed to be
edited.

$HOMEl'.Xauthority
Machine-readable authorization codes for the user's server. This file is not
designed to be edited by hand. See Chapter 4 for information on how the .Xau-
thority file is used.
Note that the user-configurable .xsession file is available only because it is exec'd by the
Xsession shell script. If you don't understand yet why this is important, consider that any
administrator can remove that functionality, or can add any other clients or resourcesto be
used by all X user sessions. So xdm configuration is unusual in that you can do just minimal
configuration (just set things up so it runs and then leave it alone) or you can go wild setting
up a global user environment.

We'll talk about all these files in detail later in the chapter. First, though, we'll give a quick
and dirty procedureto get a minimal setuprunning.

The X Display Manager 47

3.3 xdm the Easy Way

For those of you that are interested in just getting xdm working for the first time, you can fol-
low the steps below to set up xdm on a standaloneworkstation. Thesesteps assumethat you
are using the MIT-distributed version of xdm, and that the xdm configuration files have not
been changedfrom the defaults distributed by MIT.
1. Edit the Xservers file in lusrllib/Xlllxdm as needed. If you want xdm to control the local
display server,the Xservers file should contain the line:
:0 local /usr/bin/Xll/X

If you don't want xdm to control the local display server, this line should be omitted. In
all likelihood, the default Xservers file will work just fine.

2. If you're currently running the X server on the local console display, you should exit it.
It's also a good idea to have an alternate way to log in to the workstation (such as a
remote login across the network, or an ASCII terminal connectedto a serial port), since if
something goeswrong, your console may become unusable.
3. Start xdm as root:

# /usr/bin/Xll/xdm

The X server will take over your display and you should see a login box resembling that in
Figure 3-3.

harry

login:
Password:

Figure 3-3. xdm login box

48 The X WindowSystem Administrator'sGuide

 Now log in. You should get an xterm window and a twm window manager,as shown in Fig-
ure 3-4.

Figure 3-4. Default xdm environment

You can configure this environment by creating a shell script in your home directory called
.xsessionand making it executable. If written as a Bourne shell script, the rules for writing
the .xsession file are similar to those for the .xinitrc file used for xinit. Unlike .xinitrc, how-
ever, jcsessiondoes not have to be a Bourne shell script, it can be any executable. For infor-
mation on configuring individual X sessionsat the user level, seeChapter 2.
See Section 3.7 for information on how to install xdm to start at boot time.

3.4 Troubleshooting xdm

Problemswith logging in via xdm might be traced using xdm error messages.Many errors are
placed in the file lusrlliblXlllxdmlxdm-errors, but if you are using R5 xdm, the first place to
look is in the file $HOME/.xsession-errors.$HOMEI.xsession-errorscontains errors generated
only under your user account. In addition, some of the more common situations are listed
here:

" If the server doesn't start or if you don't get the login box, there is probably something
wrong with your xdm configuration files. Kill xdm from the alternate login we recom-
mended in Step 2, and look in the file lusrlliblXlllxdmlxdm-errors for hints. Good candi-
dates for mistakes of this magnitude are the Xservers, xdm-config, and Xaccessfiles. If

The X Display Manager 49

 you'd rather not deal with it, try to restore the files to the MIT defaults (or to the versions
originally distributed by your vendor) and try again.
" If you get the "Login incorrect" error, guesswhat, you typed your login name or pass-
word wrong. Try again, xdm uses the same login authentication as the login program
does, so if you can log on at the console or at any other terminal window, then you can
log on using xdm.
" If you log on and the login box returns instantly, something's wrong with your environ-
ment. Either the lusr/lib/Xlllxdm/xdm-errors file or $HOMEI.xsession-errors(under R5)
will contain error messagesthat can help you track the problem.
One possibility is that your .xsessionfile isn't executable.Try pressing Fl (or in R5,
CTRL-RETURN)after your password instead of the RETURNkey to accessthe "fail-
safe" session. This will bypass your .xsessionand give you a single xterm window,
sufficient to edit your environment. If your problem is that your .xsessionisn't execut-
able, the error messagein .xsession-errors(or xdm-errors in R3 and R4) will read
something like:
/usr/lib/Xll/xdm/Xsession: /home/judy/.xsession: Permission denied

If this is your problem, simply do:

% chmod +x .xsession

This might need to be done if you've just createdyour .xsessionfile, or if you've just
copied it from another machine usingftp.
Under R5, another possibility is that there is a problem writing to your $HOMEI.xses-
sion-errors file. One reasonthis might happenis if your home directory isn't properly
NFS-mounted from another host. The "failsafe" session won't help in this case;
instead, if you're on the console display server, pressCTRL-Rat the login box to dis-
able both the xdm connection and the X server on that display. The error messagein
xdm-errors will read:

/usr/lib/Xll/xdm/Xsession: /home/tim/.xsession-errors: Permission denied

Either your home directory doesn't exist, or your home directory isn't writable by
you, or your .xsession-errorsfile isn't writable by you ... track down the problem,
correct it, and try again.

" If you log on, windows flicker on your screen, and then the login box reappears, you
probably put all your clients in the background in your .xsession script. Press Fl after
your password to accessthe "failsafe" session and edit your .xsession. You need to put
the last interactive client in the foreground by omitting the trailing "&." See Section
2.2.3.1 for more information.

(Note that if this is your problem, xdm will not generate an error messagesince as far as
xdm is concerned,everything was executed successfully.)

Now that you have xdm working for your local display, it's trivial for it to control other X
serversat your site. If you have X terminals that are XDMCP-compatible, you should be able
to just set them up to query your host for an xdm connection. See Section 7.5.1 for more
information on setting up X terminals for use with xdm.

50 The X Window System Administrator's Guide

 Some readerswill want to stop reading this chapter right here. However, if you're interested
in refining your xdm configuration or you just want to know more about how xdm works,
please read on.

3.5 Customizing xdm

Now that we've told you the general idea of xdm and how to get it going, it's time to talk
about the gory details.
The following sectionsdescribethe xdm configuration files in detail.

3.5.1 The Master Configuration File (xdm-config)

All of the configuration files used by xdm are specified in the xdm-config file (with the nota-
ble exception of xdm-config itself), so it's worth your while to becomevery familiar with its
contents. You can consider it to be the starting point of your xdm configuration.
The xdm-config file is really just a resourcefile for the xdm client. For that reason,the syntax
for xdm-config follows standard resource specification syntax. See Appendix D for more
information on resourcesyntax (although you might be able to get through this chapter with-
out it).

The following is the samplexdm-config file as it comes from MIT in Release5 of XI1:
DisplayManager.errorLogFile: /usr/lib/Xll/xdm/xdm-errors
DisplayManager.pidFile: /usr/lib/Xll/xdm/xdm-pid
DisplayManager.keyFile: /usr/lib/Xll/xdm/xdm-keys
DisplayManager.servers: /usr/1ib/Xl1/xdm/Xservers
DisplayManager.accessFile: /usr/lib/Xll/xdm/Xaccess
DisplayManager._0.authorize: true
DisplayManager._0.setup: /usr/1ib/Xl1/xdm/Xsetup_0
DisplayManager._0.startup: /usr/lib/Xll/xdm/GiveConsole
DisplayManager._0.reset: /usr/1ib/Xl1/xdm/TakeConsole
DisplayManager*resources: /usr/lib/Xll/xdm/Xresources
DisplayManager*session: /usr/lib/Xll/xdm/Xsession
DisplayManager*authComplain: false

The keyword DisplayManager starting each resource name is the internal "class name"
for xdm. xdm usessome resourcesfor configuring xdm itself, and other resourcesfor confi-
guring its behavior once individual X display servers have connected to it. In particular,
resourcespecification in xdm-config follows one of the following forms:
Di splayManager .variable: value
or

DisplayManager. DISPLAY. variable: value

Di splayManager* vari abl e: value

In the first form, the DisplayManager keyword is separatedfrom the variable name
by a single period, meaning that this is a resource that makes senseonly when applied to

The X Display Manager 51

 xdm proper. An example of a resource like this is DisplayManager. servers, for
specifying which file should be used for listing the X serversto be managedby xdm. You
can think of this sort of resourcename as applying to Jtdw's behavior independent of its
connection to any particular X server: which serversto connect to, where to copy its pro-
cess ID, where to put error messages, etc.

" The secondform is used to specify a resourcethat should apply to a single display server
only. Here's where the tricky part to resource naming rules for xdm comes into play:
since the colon (:) has special meaning in resource specification syntax, the underscore
(_) is used where thesewould normally occur in a display name.For example, the display
name bigbird: 0 becomesbigbird_0 if it appears in a resource name. Without an
underscoreto specify that a particular server is being referred to, the name is taken to rep-
resenta group of X servers,called a display class. SeeSection 3.5.6 for more information
on display classes.

The server for which you'd most want to define a specific resource is the local console
display (: 0, specified as _0 in resource specifications). An example of one of these is
the DisplayManager ._0 . authorize resource-you usually want to enable access
control on the local server, but you may not want it enabled on X terminals if they don't
support that functionality.

" The third form of an xdm resource specification is really just a generalization of the sec-
ond form. By putting an asterisk betweenthe DisplayManager keyword and the vari-
able name, where a display name would normally be, you can define this value for all
servers not specifically defined otherwise. As a common example, you could use the fol-
lowing lines:
DisplayManager*authorize: false
Di splayManager._0.author!ze: true

and only the local display serverwill useaccesscontrol.

In resourcelingo, theseare called "loose" and "tight" bindings. We discussresourcebindings

in detail in Appendix D.
Seeyour xdm manpagefor a description of other resourcesthat can be specified in the xdm-
config file.

For testing purposes,you can use the -config option to xdm to test new configuration files. For
example, to start xdm with a customized configuration file, enter:
# /usr/bin/Xll/xdm -config ./my.xdm-config

The DisplayManager .autoRescan resource controls whether xdm automatically

rereadsthe configuration files after they have been changed.If set to true (the default), xdm
will reread the xdm-config file the next time a serverconnectsto xdm. If set to false, then if
you edit the xdm-config file while xdm is still running, you have to sendxdm a SIGHUP sig-
nal before it will be reread. See Sections 3.6.2 and 3.6.3 for more information on sending a
SIGHUP to xdm.

52 The X Window System Administrator's Guide

 3.5.2 Listing X Servers (the Xservers File)

The Xservers file was originally designed in X11R3 to list all X servers to be managedby
xdm. The XDM Control Protocol, introduced in R4, changesthe function of the Xservers file
significantly.
Under XI1R3, all X serversmanagedby xdm required entries in Xservers.The only way xdm
would know to connect to a server is if it appearedin the Xservers file at startup. In that way,
Xservers acted somewhat like an inittab for xdm.

With X11R4 and XDMCP, the X terminal takes responsibility for querying the host for an
xdm connection. For that reason,any X terminal that supports XDMCP should have its entry
removed from Xservers on a host running XI1R4 or later.
The Xservers file is not yet obsolete, however. It is still used to start the X session on the
local console display, which does not normally use XDMCPqueries. It is also used to tell xdm
how to start up the X serveron the local machine.

3.5.2.1 Xservers Syntax

The syntax for each line in the Xservers file varies on whether it's for a server that runs on the
local machine, and whether a display class is specified in Xservers for that machine. The
only X servers that you need to enter into the Xsen'ers file are those that do not use XDMCP
to request a connection. For the most part, the only X server that needs to be specified in
Xservers is the console display server. If your console display server is R4- or R5-compat-
ible, it probably supports XDMCP queries but does not have them enabled by default. So you
need to enter the local serverinto the Xservers file if you want it to be managedby xdm:
:0 local /usr/bin/Xll/X

The console display name, : 0, is followed by the word local to tell xdm that it's an X
server running on the local machine, and then by the command used to start the X server.
This command,lusr/bin/XllIX, is executed when xdm is started up. lusrlbinlXHIX is usually
a symbolic link to another serverprogram.*
Since X terminals run their server on another machine, they have a slightly different syntax
in Xservers.You only needto enter X terminals in Xservers if they don't support XDMCPor if
you're running R3 xdm on the host. The following are examples of Xsen'ers entries for X ter-
minals:

ncdl:0 foreign NCD xterminal

visualliO VISUAL-X19TURBO foreign Visual xterminal
bigbird:0 XNCD19r foreign Eileen's xterminal

* An example of when this would be useful is for a '386 workstation, on which any number of third-party monitors
might be installed, requiring multiple servers to support them all. Among the steps required to install a new monitor
may be to link X to a different server program.

The X Display Manager 53

 Managing Another Workstation's Display
It's common to use xdm on a given host to manage X terminals, but what if you want it
to managethe display server on another workstation? This can be done, it just needs a
little coordination between the two hosts. For example, if you want to set up a host rock
to managethe display of the workstation scribe, you have to do the following:
1. First of all, make sure xdm isn't being run on the workstation scribe, since you prob-
ably don't want it running. If for some bizarre reason you do want it running, make
sure that the local server isn't listed in the Xservers file on scribe-that is, if xdm is
running, make sure the following is commentedout in Xservers:
#:0 local /usr/bin/Xll/X

2. You have to decide which end you want to start the xdm connection on.
a. If you want to start the connection on the server side, have the X server started
with an active XDMCP query.
% /usr/bin/Xll/X -query rock.west.ora.com

If you want to set it up permanently,put this command in letclrc.local.

The -query option tells the X server to place a Direct XDMCP query to the speci-
fied host. Use the -indirect option in place of -query for an Indirect query to the
specified host-for example, to get a chooser box from R5 xdm (see Section
3.5.3.2 for more information on the chooser client). You can also use the
-broadcast option for a Broadcast query, in which case the first xdm host who
replies to the query gets control of the server. The -broadcast option is not fol-
lowed by a hostname.

b. If you want to start the connection on the host side,put in the Xservers file on the
host running xdm (rock in this example):
scribe:0 foreign X server on workstation "scribe"

And have the X serveron scribe started "passively", such as:

% /usr/bin/Xll/X

(Again, to set it up permanently,put this command in IetcI re.local.)

As a policy, it's probably better to have the connection started via an XDMCP query
and avoid explicitly listing hosts in Xservers. A disadvantage to listing hosts in
Xservers is that you have to make sure that you don't end up having the sameserver
listed in two Xservers files on two different hosts.If you see the following error in
the lusrlliblXlllxdmlxdm-errors file:

error (pid n) : WARNING: keyboard on display ... could not be secured

what might have happenedis that another host has the server listed in its Xservers
file and is currently running xdm on the sameX server.

54 The X Window System Administrator's Guide

 As with the entry for the local server, each of these entries starts with the display name. In
the first of these, the display name,ncdl: 0, is followed by the word foreign to signify
that it's an X server running on another machine.* The other entries are examplesof entries
for X terminals with display classesspecified. If the name of a display is followed by some-
thing other than local or foreign, it's taken as a display class. (See Section 3.5.6 for
more information on display classes.) In the example, the display classes used are
VISUAL-X19TURBOand XNCDl9r. The name of the display class is then followed by for-
eign.

The rest of the line is ignored, and can be used for a comment. In R3, beware that although
the rest of the line is ignored, it must consist of at least one word.
Note that like the xdm-config file, the Display-Manager .autoRescan resourcecontrols
whether xdm automatically rereads the Xservers file if it has been changed, or requires a
SIGHUP signal before it rereadsconfiguration files. By default, any configuration files that
have been changed are automatically reread when the next server connects to xdm. SeeSec-
tions 3.6.2 and 3.6.3 for more information on sending a SIGHUP to xdm.

3.5.3 xdm Host Access Control: the Xaccess File (R5 Only)

In XI1R5, the Xaccessfile is introduced to allow administrators to control how xdm responds
to different types of XDMCPqueries. It's important to note that the Xaccessfile is not related
to server access control, which is controlled by the DisplayManager*authorize
resource. SeeChapter 4 for information on server accesscontrol. All the Xaccessfile con-
trols is what servers can get a login window; users still need to supply their user name and
passwordwhen they actually log in.

As mentioned earlier, there are three types of queries defined for X terminals using XDMCP:
Direct, Indirect, and Broadcast. If an X terminal is set up to use "Direct," it meansthat it will
ask a particular host for a connection. If it is set up to use "Broadcast," it meansthat it will
send out a general query throughout the network, for any host running xdm to answer-for
most X servers,the first host that answersis the one that getscontrol of the terminal.
"Indirect" queries are for hosts that might forward the connection to another host, but hosts
that could actually do this were few and far betweenbefore R5 xdm. Ideally, you would want
a user to have a choice among multiple hosts to connect to. Some X servers have this func-
tionality built in, using either "Indirect" or "Broadcast" queries.But to control thoseX termi-
nals that did not have it built in, administrators had to resort to hacking xdm to support it.
This has changed with XI1R5.
With R5, the Xaccessfile starts to put all this in place. Among other things, it provides a way
of using the chooser client, which allows the user to choose among multiple other hosts.
Indirect, Direct, and Broadcastqueries are shown in Figure 3-5.

*In R3 xdm, the display type transient was used for some foreign displays. "Transient" is no longer a valid dis-
play type.

The X Display Manager 55

 Network
Direct XDMCPQuery
Direct XDMCPQuery

xdm
X server

Indirect XDMCPQuery

Indirect XDMCP Query Forward

Broadcast XDMCPQuery

Figure 3-5. XDMCP Direct, Indirect,and Broadcast queries

3.5.3.1 Direct and Broadcast Access

In its simplest form, the Xaccessfile can be usedto restrict accessto particular X servers who
request accessvia Direct and Broadcast queries. You can just list the addressesof X servers
that you want to allow connectionsfrom, using standardUNIX wildcards (? to match a single
character, * to match any number of characters). To omit a particular X serverfrom the list
of those allowed, start the name with an exclamation point (!). For example, to restrict
accessto serversin the ora.com domain, you might do:
*.ora.con

To allow connections from all X servers in the ora.com domain except for a workstation
named harry, do:

56 The X Window System Administrator's Guide

 *.ora.com
!harry.ora.com

In its MIT-distributed form, the Xaccessfile is configured to allow Direct and Broadcast con-
nections from all X servers:

* #any host can get a login window

3.5.3.2 Indirect Access and the Chooser

Until R5, the distinction between Direct and Indirect queries was poorly defined-there
didn't seemto be any difference between connecting via a Direct query or an Indirect query
to a particular host. The R5 Xaccessfile changesthat.
An Indirect query basically allows xdm on the host to determine what to do with the query. If
xdm encounters a Broadcast or Direct query, it either pops up a login box or it doesn't
(depending on whether the node is allowed accessin the Xaccess file, as described above).
Responding to an Indirect query, however, the Xaccess file gives the administrator a chance
to configure whether to respond directly, whether to pass the query on to another host, or
whether to give the user a choice between multiple hosts.
For example, to configure xdm to transfer an Indirect query from any NCD X terminals
(namedncdl, ncd2, etc.) directly to the host ruby.ora.com, you might enter in Xaccess:
ncd*.ora.com ruby.ora.com

Alternatively, you can set up xdm to respond to Indirect queries with a chooser box. This
gives the user the opportunity to choosebetween several hosts, as shown in Figure 3-6. The
chooser client, implemented via the CHOOSER keyword in the Xaccessfile, is a big plus in R5.
To allow the NCD X terminals to choose from harry.ora.com, ruby.ora.com, and
rock.west.ora.com, enter into Xaccess:
ncd*.ora.com CHOOSER harry.ora.com ruby.ora.com rock.west.ora.com

The chooser box would resemblethe box in Figure 3-7.

The chooser client itself resides in lusrlliblXlllxdm, with everything else. Note that unlike
the other files in that directory, it is not a readableASCII file, but a compiled executable.
Yet another possibility might be to set up the chooser client so it just does a broadcastamong
all hosts on the network and allows the user to choose among them. To do this, just use the
keyword BROADCAST following the CHOOSER keyword.
ncd*.ora.com CHOOSER BROADCAST

To customize the appearanceof the chooser client, use the Xresources file. The default
Xresources file definesthe following resourcesused by the chooserclient:

Chooser*geometry: 700x500+300+200
Chooser*allowShellResize: false
Chooser*viewport.forceBars: true
Chooser*label.font: *-new century schoolbook-bold-i-normal-*-240-*
Chooser*label.label: XDMCP Host Menu from CLIENTHOST
Chooser* list, font: -*-*-medium-r-nontial-*-*-230-*-*-c-*-iso8859-l
Chooser*Command.font: *-new century schoolbook-bold-r-normal-*-180-*

The X Display Manager 57

 Network

Indirect XDMCP Query

Figure 3-6. The chooser

XDMCP Host Menu from rock

harry .ora.com Willing to manage
rock. west.ora.com Willing to manage
ruby. ora.com Willing to manage

(cancel/ (accept/ (ping)

Figure 3-7. An example chooser box

58 The X Window System Administrator's Guide

3.5.3.3 Using Macros

The Xaccessfile allows you to define macros to group together a setof hosts.A macro defini-
tion starts with a percent character (%), followed by the macro name, followed by a list of
hostnames(with a backslash at the end of the line signifying that the definition continues
onto the next line). The macro is then called later on, preceded by the %. An alternative way
of allowing X terminals to chooseamong harry, ruby and rock might be:
%NCDHOSTS harry.ora.con ruby.ora.can rock.west.ora.cam

ncd*.ora.com CHOOSER %NCDHOSTS

3.5.3.4 Advantages and Disadvantages of the Chooser

The big advantagethat the Xaccessfile provides is that it can make it much easier to maintain
and control X terminals on a network. Without the chooser, the host to query is configured
directly on the setup menu of an X terminal using XDMCP. If you want to move the manage-
ment of some X terminals to another host, it may involve personally visiting each terminal
and editing their setup menus manually, step-by-step.However, using the Xaccessfile, you
can simply set up a single host as the primary xdm server, designed to accept Indirect queries
and determine where they should be transferred. Using this scheme,switching xdm manage-
ment from one host to another is a matter of editing a single file.
In our bicoastal environment, we use the chooser to allow East Coast employees to access
their environmentsfrom the West Coast without having to do contortions: they simply choose
the East Coast xdm host and they are greeted by the samefriendly login box they're used to
at home.

A problem with the chooser functionality is that due to a bug in R4 xdm, it can be used only
to transfer xdm control to another host running R5. For example, if you had in your Xaccess
file:

%R5HOSTS harry.ora.com ruby.ora.com rock.west.ora.com

%R4HOSTS opal.ora.com

* CHOOSER %R5HOSTS %R4HOSTS

with opal running R4 xdm, the chooserbox would look like the one in Figure 3-8.

Note that only the R5 hosts (harry, ruby and rock) are reported as "Willing to manage." If
you select one of the R5 hosts you'll get the xlogin box as expected;but although the R4 host
is listed, if you select opal you'll be temporarily "hung" and then you will be returned to the
chooserbox without a chanceto log on.
Note that like the xdm-config file, the DisplayManager. autoRescan resource controls
whether xdm automatically rereads the Xaccess file if it has been changed, or requires a
SIGHUP signal before it rereads configuration files. By default, any configuration files that
have been changed are automatically reread when the next server connectsto xdm. A mes-
sageappearsin the xdm-errors file:
info (pid 1564): Rereading access file /usr/lib/Xll/xdm/Xaccess

SeeSections 3.6.2 and 3.6.3 for more information on sending a SIGHUP to xdm.

The X Display Manager 59

 XDMCP Host Menu from rock
host opal
harry.ora.com Willing to manage
rock.west.ora.com Willing to manage
ruby.ora.com Willing to manage

(cancel)(accept)(ping)

Figure 3-8. Chooser box with an R4 host

3.5.4 The Xresources File

The Xresources file is loaded into each individual X server as it is connected to xdm. The
most important function of the Xresources file is to set resourcesfor clients or widgets that
are run before the user actually logs in. In particular, the xlogin widget's resourcesneed to be
loaded into the server by xdm itself, since it is (by necessity) run before the user logs in. In
R5, the chooser and xconsole clients may also be run before the user logs in, so those clients
need their resources specified in Xresources as well.

As each X server connects to xdm, the resources in the Xresources file are loaded by the
server via the xrdb client. See Section D.I.3 for more information on xrdb.

3.5.4.1 Configuring the Login Box

The login box displayed on an X server controlled by xdm can be configured using the
Xresources file. In its default configuration, that file contains the following lines:
xlogin*login.translations: #override\
Ctrl<Key>R: abort-display()\n\
<Key>Fl: set-session-argument(failsafe) finish-fieldO\n\
Ctrl<Key>Return: set-session-argument(failsafe) finish-fieldO\n\
<Key>Return: set-session-argument() finish-field()
xlogin*borderWidth: 3

60 The X Window System Administrator's Guide

 xlogin*greeting: CLIENTHOST
xlogin*namePrornpt: login: \
xlogin*fail: Login incorrect
#ifdef COLOR
xlogin*greetColor: CadetBlue
xlogin* faiiColor: red
*Foreground: black
*Background: #fffffO
#else
xlogin*Foreground: black
xlogin*Background: white
#endif

The resources starting with the string xlogin are used by the xlogin widget, xlogin sends
the box to the display, prompting the user for a name and password. The xlogin box typically
resemblesFigure 3-3.
Note that the first resource for xlogin is a translation table, used for defining how special
keystrokes might be used within the client. (See Section D.I.4 for more information on
translation tables.) This translation table is particularly important. What it does is to allow
you to log in without running your .xsessionfile, by pressing Fl after your password instead
of RETURN.*

Instead of running your .xsession,pressing Fl tells xdm to run a "failsafe" X session,defined

as a single xterm window. (You can actually change this in the Xsession file. See Section
3.5.5 for more information on the Xsession file.) This is important, since otherwise you may
have no way of logging in if your .xsessionis corrupted.
The other important translation listed here is that you can use CTRL-R to stop xdm from
managing your display entirely. This feature, new to R5, is useful for the local console dis-
play, where you might want to return to the console to start another windowing system or
load a different X server image. Note that this only works if the X server isn't initiating
XDMCP queries; otherwise, CTRL-R will abort the current xdm connection, but a new one
will instantly replace it.
The remainder of the resources set for xlogin are fairly straightforward, used largely to spec-
ify the messagesused for prompts and error messages.Note that since this resource file is
loaded into the server via xrdb, cpp pre-processorcommands(particularly #ifdef, #else,
and #endif) can be used. In the R5 default shown above,the pre-processorcommandsare
used to specify how the xlogin box should appear, depending on whether the display has
color support. COLOR is one of the variables that are pre-defined in R5 xrdb; see Section
D.I.3 for more information on xrdb pre-defined variables.

One resource you may want to change is the greeting in the xlogin box. In previous releases
of XI1, this box said "Welcome to the X Window System" by default; in R5, it simply gives
the hostname,as shown in Figure 3-3. If you want to change this greeting, edit the resource
definition:

xlogin*greeting: CLIENTHOST

* Alternatively, in R5 you could also enter CTRL-RETURN, for those users who don't have an Fl key.

The X Display Manager 61

 to something like:
xlogin*greeting: CLIENTHOST's House Party

The resulting login box will look like the one in Figure 3-9.

harry 8 House Party

Figure 3-9. Adapted xlogin greeting

See the xdm manpagefor more information on xlogin resources,including the default transla-
tion table.

3.5.4.2 The xconsole Client

As of R5, the Display-Manager ._0 . setup resourceis used to point to a script to be run
whenthexdmconnectionto thelocal displayserveris initialized.The script,XsetupJ),sim-
ply runs the xconsole client:
#!/bin/sh
xconsole -geometry 480x130-0-0 -daemon -notify -verbose -fn fixed -exitOnFail

This ensuresthat console messagesare sent to a window in between console logins, rather
than spewing acrossthe screenand disrupting the display. The resourcesfor xconsole are set
in Xresources:

62 The X Window System Administrator's Guide

 XConsole.text.geometry: 480x130
XConsole.verbose: true
XConsole*iconic: true
XConsole*font: fixed

Seethe manual page for xconsole for more information.

3.5.5 Starting Up Individual X Sessions (the Xsession File)

Now that you have a picture of how xdm starts up and finds out how to respond to individual
display serverson the network, it's time to discussthe part where the user actually logs in.
What happensnow is completely up to the administrator. All xdm knows about is that it exe-
cutes the file pointed to by the session resource for that display. In the distribution of R5,
that file reads:

#!/bin/sh

exec > $HOME/.xsession-errors 2>&1

case $# in
1)
case $1 in
failsafe)
exec xterm -geometry 80x24-0-0

startup=$HOME/.xsession
resources=$HOME/.Xresources

if [ -f $startup ]; then
exec $startup
else
if [ -f $resources ]; then
xrdb -load $resources
fi
twm &
exec xterm -geometry 80x24+10+10 -Is
fi

See Section 2.2.3 for more information on configuring the .xsessionfile.

" The first thing that happens is that all subsequenterror messagesare sent to a file in the
user's home directory called .xsession-errors. In R4 and earlier, users' error messages
were mixed in with all other errors in the file pointed to by the Display-
Manager . errorFile resource,usually xdm-errors.
" Next, if the script has been called with the failsafe argument, a single xterm window
is sent to the display and the script exits. Where does this argument come from? Well,
rememberin the Xresources file, under the xlogin translation table:
<Key>Fl: set-session-argument(failsafe) finish-field()\n\
Ctrl<Key>Return: set-session-argument(failsafe) finish-fieldO\n\

The X Display Manager 63

 We told you that this key translation set things up so if you typed Fl or CTRL-RETURN
after your password instead of RETURN,you would avoid running your .xsessionscript
and would get a lone xterm instead. Now you know how that gets implemented. Admin-
istrators can use this as a model to write translations that pass other arguments for Xses-
sion to interpret.

" Next, the script looks for a script in the user's home directory called .xsession.If it exists,
it execs it.

" If the .xsessionscript doesn't exist, the Xsession script creates a workable X session by
first looking for a resource file called .Xresources,and if that file exists, loading it with
xrdb\ regardless,it then starts the twm window managerand a single xterm window.

This is actually a fairly simple script, when you consider that it controls every X servercon-
necting to xdm. It also gives the administrator an unusual amount of power over each X ses-
sion. At the most innocuous, an administrator could use the Xsession file to add some func-
tionality that all usersmay need-for example, to add a local font directory into font paths
using the xset client. At a slightly more intrusive level, the administrator could use it to set up
a message-of-the-dayclient for usersto seewhen they first log in. But there are really no lim-
its-an administrator could set up a network so that users have no control at all over their
own X sessions(by removing the line that executes.xsession),and in fact don't have xterm
windows to start new clients (presuming that all they'd want to do is run a mail client and a
word processor).

Note that the Xsession script is defined as a loose binding, DisplayManager*session.

You could therefore setup a separateX sessionfile for particular X servers.For example, you
might want to set up an X sessionfile called Xsession_0:
Display-Manager ._0 .session: Xsession_0

The only difference in Xsession_0 might be that the xterm called in the failsafe situation
would be called with -C, so that consolemessageswill be diverted to this xterm window:
exec xterm -geometry 80x24+10+10 -Is -C

(See Sections 4.6.1 and 4.6.2 for more information on the xterm console window.)

You can also use display classesto group severalX terminals together. SeeSection 3.5.6 for
more information on display classes.

3.5.5.1 No Home Directory? (R5)

The redirection of error messagesto $HOME/.xsession-errorsis a nice addition to R5-it

means that if users are having problems, they don't need to weed through the systemwide
xdm-errors file, but can start looking for problems locally. This makes life easier for users
and administrators alike. However, it does present a problem if for some reason you don't
have a home directory on the host.
Since Xsessionis executed as a Bourne shell script, the line:
exec > $HOME/.xsession-errors 2>&1

64 The X Window System Administrator's Guide

 producesa fatal error if it cannot be completed. One reason that may happenis if you don't
have a home directory, either becauseit's a new machine or becausethere is a problem with
your NFS link. The shell tries to create a file in a directory that does not exist and when it
can't, the script aborts. The effect is that the user logs in and is immediately bumped out,
with no sign of what happenedexcept in xdm-errors:
error (pid 2547): can't lock authorization file /home/lmui/.Xauthority or
backup /usr/lib/Xll/xdm/.Xautha02547
error (pid 2547) : No home directory /home/lmui for user Imui, using /
/usr/lib/Xll/xdm/Xsession: /home/lmui/.xsession-errors: No such file or
directory
error (pid 2549) : fatal 10 error 32 (Broken pipe)

To remedy this situation, you might change the line in Xsession to read:
if [ -d $HOME -a -w $HOME ]
then
exec > $HOME/.xsession-errors 2>&1
fi

3.5.6 Display Classes

Display classesprovide a way to group together several X servers connecting to the same
host. The display class is built into the X server, and is presentedto xdm when the X server
connects via XDMCP. To find out the display class for a given X terminal, you can look it up
in the documentation or ask the manufacturer; or, if it won't disturb any users, kill xdm and
then restart it at a high "debug" level:
# /usr/lib/Xll/xdm -debug 9

Running xdm at this level of debugging is likely to give you far more information than you
really want. Among this streamof messages,however, is information about any X server that
connectsto xdm, including its display class:
Starting display visual5.ora.com:0,VISUAL-X!9TURBO

This tells us that the Visual X terminal we're experimenting with is in the display class
VISUAL-X19TURBO.*

Display classes come in useful in allowing you to fine-tune your xdm configuration differ-
ently according to the display type. Thus far, almost all our examples of display-specific
resourceshave been about the local display server, _0. However, becauseof hardware pecu-
larities, there are situations when you would want to set resourcesfor individual X serversor
for a group of X servers.
For example, the Visual X19TURBO terminal has 2-bit gray scale support. This is nice,
except that it confusesFrameMaker into thinking it has color support. FrameMaker therefore
tries to show menus with its color defaults of black text on blue background; the X terminal

*In XI1R3, XDMCP was not available, so the Xservers file was used to explicitly list the display class used by an X
server; see Section 3.5.2.1 for more information.

The X Display Manager 65

 "

- - - -' - _
. . . . .- : -. .: -._-:-".- -;_-.- _- .. . -- : -: .
T' . - - -
. . -.-;.: . _-: - ; . - "- _ . . . v. -

play, the new user win need the same resource set for his account as well.
should be set at the server teveL

jp a separateXsfssion file to re used only for die Visual

-. - .

_^r iir xii - iaessicc

-
sessi sr LIT "/_ -

:
.

~-r

.- -
; - : -
. . r r : : I-
':::"-_

Fhe X19TURI rce loaded imc ±eir

~.ptedependscr. nersu , ,v in their own jcsessionscripts, or

±e v=>:-sr*E = :-:rr : _r. i -:

3.6 Testing Your xdm Setup

After you modify the z^in files to reflect your system,rake it out for a test drive. Beware that
testing xdm on a systemothers are using is likely to be extremely disruptive. For that reason.
.ic :o find out if anyixxr- else ii r_r_- t ilread> on your network. In case your
console gets bong in a weird state (not unu~11 -- good idea to have an alternate way to
log into the system,either over the network i e.g.. via :elne:>.or from a terminal attached to a
serial port on the system. On a PC UNIX machine, you can simply use one of the alternate
consoles available by holding down the CTRL and ALT keys while pressingone of the func-

:-. -f "" .. -;; 5.5'f- -:~ " 5"= :' ~

 You can test xdm by starting it from the commandline:
* /usr/bin/Xll/rd»

If you are doing mis on the console display and the console is set up to be managedb>
beware that your current login will become unusable once xdm is running. If you * -
makp small changesto the configuration files without restarting xdm. it might reread the con-
figuration files on its own (if the DisplayMar.arer .autoi ^s ran resource
true), or you can tell it to reread the files by sending it the SJGHLP signal. " SeeSections
3.6.2 and 3.6.3 for more information.)

Remember that you can use the -config option to xdm to specify a configuration file other
man xdm-config. It's generally a good idea to use this feature while te .
leave the default configuration intact while you edit your own files. For txamf
create a new file called xdm-testconfig. containing:
rcrlocF: - e: _Er - : XL1 XZT. te5i:cT~- errors
_=r l_r XI 1 x±r. tesotor-rii
_5r lit XU :--:±-. -.-=5-_--:±---c=r/s
_fr lij: Id x±r. tes^ls^- -^r =

. _ . . - - "i^icr" - ~ i.r*- ~
_^ r L^i: XI 1
_£r lir Xll
_5r 1^;: Xll
_^r l^r >Z1
1 1 rp Lr-^fcr^arer * sessi or. : _; r liJ: Xll x±- : T f : Isessicc
Disp] agManarer*=.utJ^

And call z<im with the command line:

# /usr/lib/Zll/zdB -config xar-resrcrz-f ig

3.6.1 Resetting the Keyboard

On Sun workstations, the abnormal termination of the X >: - a. ma

weird state. (If you don't know what we mean by mis. :
know it.) MIT provides the command usrbinXll ".-
Sun workstation. Since your keyboard is unusable,you'll hive to o
-z. ; - r-:r; 7_: --

# /usr/bia/Xll/kbd_node -a > dev console

If you manage to render me system totally unusable and cannot recc

reboot Since you haven't yet added the xdm daemonto the system boot proce-
vour svstem back to a usable state after a reboot.

-f ' : s: =. '.' =-=;?" 67

3.6.2 Restarting xdm Using xdm-pid (R4 and Later)

In R4 and R5, the xdm processID is stored in whatever file is pointed to by the Display-
Manager .pidFile resource,xdm-pid in the default configuration. If you are running R4
or R5, you can use the xdm-pid file to senda signal to xdm. This file contains the process ID
of xdm.

# cat /usr/lib/Xll/xdm/xdm-pid
28683

You can sendxdm the SIGHUP signal by using the cat output directly:
# kill -HUP 'cat /usr/lib/Xll/xdm/xdm-pid"

The xdm processshould now reflect the current configuration files for any new sessions.
If xdm becomesunusableand you are not able to fix it by editing the configuration files, you
can kill it for real. (You'll have to use a more severesignal (S1GTERM)to tell it you are seri-
ous.)
# kill -TERM 'cat /usr/lib/Xll/xdm/xdm-pid'

Beware that all active sessions managed by xdm will be killed if you use SIGTERM.

3.6.3 Rereading xdm Configuration Files (R3)

To force xdm to rereadits configuration files on an R3 system,you need to find the processID
of xdm manually in order to kill it.
First find the process ID of the parent xdm process using the ps command. Then send the
SIGHUP signal to the process.
% ps agx|grep xdm
2547 IW 0:30 -xterml:0 (xdm)
13511 IW 0:56 -xterm2:0 (xdm)
13757 IW 0:58 -xterm4:0 (xdm)
15199 IW 1:08 -xterm5:0 (xdm)
19175 S 1:51 -xterm7:0 (xdm)
19466 IW 2:08 -xterm3:0 (xdm)
28683 IW 0:09 /usr/bin/Xll/xdm
28685 S 2:07 -xterm9:0 (xdm)
28743 IW 0:00 /bin/sh /usr/lib/Xll/xdm/Xsession
17796 pO S 0:00 grep xdm

The parent xdm stands out, since the xdm processesassociatedwith a particular display
change their namesto the name of the display. (The argumentsto the ps command, as well as
its output, will vary according to the flavor of UNIX you are running.) If you send signals to
the wrong xdm process, only the display being controlled by that xdm process will be
affected.

68 The X Window System Administrator's Guide

 Controlling scologin
scologin (the version of xdm on Open Desktop, which runs on SCO UNIX machines) has
its own ways of starting and restarting the display manager.The scologin daemon has a
front end, Ietclscologin, which takes the following options:
start Starts the scologin process; if scologin is already running, the start com-
mand will causescologin to reread the configuration files Xconfig, Xservers
and Xresources.

reread If scologin is already running, the reread command will causescologin to

rereadthe configuration files Xconfig, Xservers and Xresources.
stop Stops scologin. All X sessions currently managed by scologin will be
halted.

query Returns the current statusof scologin.

disable Stopsscologin and disables it from restarting when the system reboots.
enable Starts scologin if not already running, and ensures that it will start automati-
cally at the next reboot.

init If scologin is enabled, the getty processeson terminals configured for scolo-
gin are disabled. This option should be run only by init at boot time.
For example, to have your configuration files reread, enter:
# /etc/scologin reread

3.7 Permanent Installation of xdm

When you are happy with your xdm setup, it is time to install it so it will start automatically
when the system boots. The way you do this is systemdependent,but it is the sameprocedure
as adding any other kind of daemon. In a typical BSD system, you would modify the
/etc/re.local script. Under System V, edit letclinittab. (Remember to keep backup copies of
any systemfiles you modify!)
Here are a few examplesof installing xdm on various platforms:
Installing xdm on SunOS 4.1.1
Add xdm to I etcl re.local:

if [ -f /usr/bin/Xll/xdm ]; then
/usr/bin/Xll/xdm; echo -n "XEM"
fi

Then reboot the system.

The X Display Manager 69

 Installing xdm on Ultrix 4.2
Add xdm to I etc I re.local:

[ -f /usr/bin/Xll/xdm ] && {
/usr/bin/Xll/xdm & echo -n "xdm " > /dev/console
}

Then reboot the system.

Installing xdm on a System V Machine (IRIX 4.0)

(Your system may already be set up for running xdm as shipped. Check before contin-
uing.)
Add xdm to letclinittab:

xw:23:respawn:/usr/bin/Xll/xdm -nodaemon

Then reboot the system.

Installing xdm on AIX 3.1

Add xdm to letc/rc.tcpip:
start /usr/bin/Xll/xdm "$src_running"

Then reboot the system.

3.8 Related Documentation

For more detailed information on xdm and its resources,seethe xdm manual page.
For documentation on XDMCP, look in the X source distribution, in mit/hard-
copy/XDMCP/xdmcp.PS.Z.

"The X Administrator: Taming the X Display Manager," by Miles O'Neal, published in The
X Resource,Issue 4, O'Reilly & Associates,Inc., Fall 1992.

70 The X Window System Administrator's Guide

 Security

Because X runs in a networked environment, it's particularly important that

administrators be aware of its security lapses and how to reduce the risks of
running X. This chapter discusses security issues as they relate to X.

In This Chapter:
Host-based Access Control 74
The/etc/Xn.hosts File 74
The xhost Client 75
Problems with Host-based Access Control 76
Access Control with MIT-MAGIC-COOKIE-1 77

Using MIT-MAGIC-COOKIE-1with xdm 78

Thexauth Program 79
Using MIT-MAGIC-COOKIE-1with xinit 81
xauth vs. xhost 82
The XDM-AUTHORIZATION-1Mechanism (R5) 83
TheSUN-DES-1 Mechanism (R5) 84
Public Key Encryption 85
Prerequisites for Using SUN-DES-1 86
Using SUN-DES-1with xdm 88
Using SUN-DES-1with xinit 89
Adding Another User with SUN-DES-1 91
xterm and SUN-DES-1 92
Troubleshooting SUN-DES-1 92
xterm and Secure Keyboard 93
Other Security Issues 94
The Console xterm (R4 and Earlier) 94
The Console and xdm (R5) 95
Hanging the Server Remotely (R3) 96
Reading the Framebuffer (Sun Workstations) 96
Removing Files in /tmp 97
The Network Design 97
Related Documentation . ..98
 4
Security

X runs in a networked environment. Because of X's design, your workstation is no longer

your private preservebut hypothetically can be accessedby any other host on the network. If
you are on the Internet, your display may be accessibleworld-wide. This is the true meaning
of the server concept: your display can serve clients on any system, and clients on your sys-
tem can display on any other screen.
The possibilities for abuse are considerable. When our office was introduced to XI1, one of
the first things we learned how to do was to play pranks on one another. Call it a "learning
experience"-we became familiar with X by sending prank clients to remote servers:xmelt
to make someone's screen melt away, xsetroot to put a giant bitmap picture of our boss on
someoneelse's root window, etc. When we got a hold of anything "neat" (e.g., kaleidoscope,
a GIF file of Bart Simpson, a bitmap of Bill the Cat), we fired it off to a friend's display to
amuse him, and then ran down to his office to see his reaction.

If this scares you, it should. Within our office, among our friends, we had no intention of
hurting anyone,and if anyone seemedbusy or grouchy we left them alone. But if good inten-
tions were enough, none of us would have passwordsfor our accounts. Having unlimited
accessto someone'sdisplay leaves a lot of potential for seriousdamage.Our pranks involved
clients that the user could see,be amused(or annoyed) by, and then promptly kill. However,
if you can run one client on a display then you can run any other client on that display.
The X Window Systemdesign allows any client that successfully connectsto the X server to
exercise complete control over the display. This means that clients can take over the mouse
or the keyboard, send keystrokes to other applications, or even kill the windows associated
with other clients.

It is difficult to make X completely secure. However, there are four accesscontrol mecha-
nisms, one host-based and three user-based.The host-based scheme involve a system file
(letclXn.hosts) and can be controlled using the xhost client. The user-basedschemesinvolve
authorization capabilities provided by the xauth program and by the X Display Manager
Control Protocol (XDMCP). There is also a "secure keyboard" feature in the xterm terminal
emulator that can provide protection against someproblems.

Security 73
 4.1 Host-based Access Control

One way of protecting againstunauthorizedclients is to use host-basedaccesscontrol, shown

in Figure 4-1. The way this works for workstations is that, by default, the server running on
the local workstation only acceptsclients that are running on that workstation. For example,
the local display sapphire: 0, which runs on the console of the host sapphire, would only
acceptclients started on sapphire.
For the local display server of a workstation, the list of hosts that can send clients to display
on sapphire:0 can be supplementedby adding a hostnameto the letclXn.hosts file (where n is
the number of the display), or by using the xhost client. Many X terminals also support host-
basedaccesscontrol (sometimescalled "TCP/IP accesscontrol"), with the list of hosts speci-
fied on the setupmenu or uploadedvia remote configuration from the host.

Hosts

opal.ora.com
sapphire.ora.com
ccavax.camb.com
Network

OK
ClientProgram

X server

sapphire:0
0 Client
Program Denied

Figure 4-1. Host-based access control

4.1.1 The /etc/Xn.hosts File

The /etc/Xn.hostsfile contains a list of systemsthat are allowed to accesslocal server n. On

most workstations, only one serverruns at a time, so letclXO.hostsis the only file you needto
be concerned with. This list of hosts is read by the server at startup time. The letc/XO.hosts
file can be edited so that it contains the list of systems you want to allow accessto your
server on a regular basis. For example, the file letclXO.hostson the host sapphire might con-
tain the following:
opal.ora.con
sapphire.ora.com
ccavax.canto.com

74 X WindowSystemAdministrator'sGuide
 (The letclXO.hostsfile is not included in any default configurations of XI1, but needsto be
createdby the system administrator.)
In this example, the local server sapphire: 0 can be accessedby the hosts named opal and
sapphire in the ora.com domain, and ccavax in the camb.comdomain. (Hosts in the current
domain do not require the domain name suffix, but it's a good practice to always use fully-
qualified domain names,to prevent a machine named opal in another domain from connect-
ing to the server.) If you try sending a client to the sapphire display from a host not on that
list, the client will be rejected:
lmui@ruby % hostname
ruby
linui@ruby % xterm -display sapphire: 0
Xlib: connection to "sapphire:0.0" refused by server
Xlib: Client is not authorized to connect to Server
Error: Can't Open display

Note that hardcoding hosts into letclXn.hosts makes senseonly for workstations used by a
single user,since the list of hosts you want to enable accessfrom is likely to be user-specific.
If a workstation is in a public area and is used by many different users, then the host access
list is likely to change,and only the administrator should be able to edit letclXn.hosts.
X terminals that support host-basedaccesscontrol have the hostnamesmanually addedto an
accesscontrol list on the setup menu.Seeyour X terminal's documentationfor details.

4.1.2 The xhost Client

To supplement the letclXn.hosts file, the xhost client can be used to give (or deny) systems
accessto the server interactively. To use the xhost client to add ruby.ora.com to the list of
hosts that can display to sapphire: 0, you have to run xhost in an xterm window running
on sapp hire:
lmui@sapphire 87% xhost +ruby.ora.com
ruby added to access control list

The sapphire :0 display will now be able to display clients from ruby in the domain
ora.com.

You can only run xhost from a window displaying on the server in question. If you try run-
ning xhost from a remote display, you get the error:
xhost: must be on local machine to add or remove hosts.

Specifying a hostname with an optional leading plus sign (+) allows the host to accessthe
server, and specifying a hostname with a leading minus sign (-) prevents a previously
allowed host from accessing the server. (Note that removing a host applies only to future
requests from clients to the display-it's too late to stop any clients that are already con-
nected.) Multiple hosts can be specified on the same line. Running xhost without any argu-
ments prints the current hosts that are allowed accessto your display.
To allow accessto the local display from all hosts,enter:
% xhost +

Security 75
 Needlessto say, we strongly discourageyou from doing this.
You can use the xhost client to.enable accessfrom a specific host only long enough to start up
clients from that host, and then disable accessimmediately. For example, a script might do
somethinglike this:
xhost +sapphire
rsh sapphire xterm -display reno:0
sleep 15
xhost -sapphire

You can also use the remote host's IP address instead of the hostname.

% xhost +140.186.65.13

The IP address is useful when the remote hostname isn't known to the name server. (The
name server translates domain names into IP addresses.) Also, in the rare case when a host is
on two different networks and has two different IP addresses,xhost may get confused. You
might have to explicitly specify the IP addressthe host uses on the current network. (The
better solution is to fix the problem for good, by re-linking X with updated resolver libraries;
but in the interim, using the direct IP addressmay do the trick.)

If the above description left you in the dark-if you don't know name servers from X
servers,and IP addressesare greek to you-consult the Nutshell Handbook TCP/IPNetwork
Administration by Craig Hunt (O'Reilly & Associates, 1992).

4.1.3 Problems with Host-based Access Control

Host-basedaccesscontrol is better than nothing, but it has some basic conceptual problems
that make it insufficient for true security. One problem is that, while the primary reason for
denying a remote system accessto your display is to prevent a person working on the remote
system from displaying on your server, this also prevents you from running clients from that
remote systemon your display. So you have to deny yourself functionality in order to deny it
to others.

The main problem with host-based accesscontrol, however, is that it's easy to get around.
It's a great idea if workstations are really single-user machines, where only the person who
actually usesa given host has an account on it. But on today's UNIX networks, you are proba-
bly running yellow pages(NIS) to simplify account allocation and file permission issues.On
these networks, as long as a prankster has an account on one of the hosts you do allow access
from, xhost provides no protection. Any user with an account on your machine (or any other
host your server allows accessto) can accessyour display.
On an X terminal, host-basedaccesscontrol makes even less sense.X terminals are depen-
dent on a host to run almost all of its clients. That host is often a compute server usedto sup-
port several other X terminals as well. So X terminals that support host-basedaccesscontrol
generally need to list a host with many other users on it, meaning that all those users can
accesseach others' displays. This is still better than nothing, but definitely not secure.
If you're running Secure RPC, you can use the SUN-DES-1method of security and use xhost
to give accessto a particular user in a given domain, such as "xhost +dave@ora. com."
This is really the best way to control accessto a server,since it is entirely user-based. Not all

76 X WindowSystemAdministrator'sGuide
 machines support Secure RFC, however. See Section 4.4 for more information on SUN-
DES-1.

4.2 Access Control with MIT-MAGIC-COOKIE-1

With Release 4 of XI1, a user-based access control mechanism can be used to supplement or
replace host-based accesscontrol. User-basedaccesscontrol is built into the XDM Control
Protocol (XDMCP),but it can be used independently of xdm. In Section 4.2.3, we show how
you can use it with xinit. In addition, it is automatically enabled when the openwin server is
started under OpenWindows.
The most common method of user-basedaccesscontrol (and the only one available under
R4) is a mechanism known as MIT-MAGIC-COOKIE-1.This schememight be called permis-
sion-basedrather than user-based,since it depends on UNIX file permission more than any-
thing.

If both the host and the X server are configured to use MIT-MAGIC-COOKIE-1, then when you
log in using xdm, a machine-readablecode is put in a file called .Xauthority in your home
directory, belonging to you. This is shown in Figure 4-2. This code, called a magic cookie, is
also told to the server. The magic cookie code can be thought of as a password known only
to the server and to the user who logs in using xdm. Users don't have to actually type the
code at any point, they just needto be able to run the programsthat manipulate it.

Network Host
WOMIT-MAGIC-COOKIE567.. #A#OMIT-MAGIC-COOKIE567..

/home/fred/.Xauthority

X server

Figure 4-2. XDMCP and the access code

Once the code is established for that X session,a client must present the code before it is
allowed to connect to the server. The client gets the code by reading the .Xauthority file in
the user's home directory. This file has the permissions"-rw ", meaning that it can
be read and written only by the owner. The MIT-MAGIC-COOKIE-1mechanism therefore
takes advantageof the fact that all processesstarted by a user inherit that user's permissions.
Figure 4-3 shows a user who does not have accessto the code being rejected.

Security 77
 Access Code

#A#OMIT-MAGIC-COOKIE567.

Network Host

OK
/home/fred/.Xauthority
#A#OMIT-MAG
IC-COOKIE567..

X server

Client 2 /home/bob/.Xauthority

Denied

Figure 4-3. User-based access control

Since this type of accesscontrol is based entirely on UNIX file permissions, it is only as
secureas the user's account-if you don't have a password,for example, it's totally useless
since anyone can log in as you and then do whatever they want to your server.

User-based access control is clearly more secure than host-based access control, but it
dependson the serverbeing programmed to take advantageof it. Not all X terminals are cap-
able of using the magic cookie. Furthermore, magic cookie-type accesscontrol is tightly
bound to the operating system,which is not in the spirit of X.

4.2.1 Using MIT-MAGIC-COOKIE-1with xdm

In Chapter 3, we discussedthe resourcesfor xdm specified in the xdm-config file. In addition

to pointers to several special files, the xdm-config file contains theseresourcespecifications:
DisplayManager._0.authorize: true
DisplayManager*authorize: false

The first resource specification turns on authorization for the local display. The second one
turns the schemeoff on all other displays. To turn authorization on for any other serversthat
are connected to the host, change the secondresourcedefinition:
DisplayManager*authorize: true

xdm is probably configured to reread the configuration file on its own (by setting the
Display-Manager .autoRescan resource, which is on by default), but if not, you can
sendxdm a SIGHUPso it will reread its configuration file:
root* kill -HUP Ncat /usr/lib/Xll/xdm/xdm-pi<r

78 X WindowSystemAdministrator'sGuide
 In addition to this, some X terminals need to be explicitly configured to use MIT-MAGIC-
COOKIE-1.Seeyour X terminal's documentation for more information.

4.2.2 The xauth Program

A problem with user-basedaccesscontrol is that it relies on all your clients having accessto
the magic cookie. This is reasonableto expect if you run all your clients on the samehost or
if your home directory is shared(for example, using NFS or AFS) acrossall the hosts you run
clients on. Since all the necessaryinformation is in your $HOMEl.Xauthority file, you can
accessyour server from all hosts with the same shared home directory. But what about the
situation when you want to run clients from a host that does not have a shared home
directory?
The solution is a program called xauth, used to propagate the magic cookie from one host to
another. The most common use for xauth is to extract a user's authorization information for
the current display, copy it to another machine, and merge it into the $HOMEi'.Xauthorityfile
on the remote machine, as shown in Figure 4-4. From a host where the user already has the
magic cookie listed, this can be accomplishedwith the following commandline:
% xauth extract - $DISPLAY I rsh remotehost xauth merge -

For example, to share the authorization information for the reno: 0 display with your user
account on the host ruby, type:
% xauth extract - reno:0 I rsh ruby xauth merge -

The extract function takes the magic cookie from the .Xauthority file in your home directory
on reno. Since you may be logged on at severaldifferent displays at once, you needto spec-
ify which display you want to extract the magic cookie for. In the example above, we want to
extract the magic cookie for the local display server, reno:0. By using a dash (-), the
magic cookie is written to standardoutput.

The xrsh Command

If you run remote clients using the xrsh shell script provided in the R5 contriblcli-
entslxrsh directory, xauth is automatically run to propagatethe magic cookie code to the
remotemachine before the remote client is started.For example:
% xrsh -auth xauth ruby xterm

startsup xterm on the host ruby after first using xauth to transfer the cookie.
If you use host-based accesscontrol, xrsh can also give the remote host accessto the
server. This is the default behavior:

% xrsh -auth xhost ruby xterm

You can also set the XRSH_AUTH_TYPEenvironment variable to specify which type of
authorization you need enabled for the remote host. The default behavior is for xhost
authorization.

Security 79
 Access Code
#A#OMIT-MAGIC-COOKIE567.

Network Hosfl

xauth
extract
-reno:0 "j H /home/fred/.Xauthor
|[

X server
"reno:0" Host 2

xauthmerge- /usrl/fred/.Xauthority

F/gure 4-4. Propagating the magic cookie between two hosts

The xauth merge function acceptsmagic cookie codes from the specified file-in this case,
from standardinput. It then merges that information into the $HOMEl'.Xauthorityfile on that
system.

Since only you have accessto the magic cookie for your server, only you can successfully
run xauth to send that code to another host.

Particularly picky readersmight point out that technically, xauth is not a client program since
it never contacts the X server itself, but is simply used to manipulate the .Xauthority file.
Our examples so far have only shown how to use xauth to extract the magic cookie code from
a local machine and merge it into a remote one. But it's just as easy to do it the other way
around. In the following example, we rlogin to a machine called rock, try to run an xterm
window, and when we are rejected we simply copy the magic cookie and try again. Note that
as far as the shell is concerned, reno is now the remote machine and rock is the local one, so
rsh needs to be called on the xauth extract command.

lmui@reno 79% rlogin rock

Last login: Fri Sep 18 07:27:17 from ruby.ora.con
SunOS Release 4.1.2 (ROCK) #1: Fri Sep 11 17:56:56 PDT 1992
lmui@rock % xterm -display reno:0
Xlib: connection to "reno:0.0" refused by server
Xlib: Client is not authorized to connect to Server
Error: Can't open display: reno:0
lmui@rock % rsh reno xauth extract - reno:0 I xauth merge -
lmui@rock % xterm -display reno:0 &
(client runs successfully)

It's also possible to copy a code from one host to another from an uninvolved third host, but
it's hard to come up with a circumstancein which you'd need to do that.

80 X WindowSystemAdministrator'sGuide
 Note that since xauth depends on using rsh, it requires that you have set up either
$HOMEI.rhostsor /etc/hosts.equiv on the remote machine to permit the remote shell com-
mand. If you get a "Permission denied." error, it's because your account on the
remote system isn't configured to allow remote commandsfrom the local system,not because
of any problem with X. SeeSection 2.3.4.1 for more information.

4.2.3 Using MIT-MAGIC-COOKIE-1with xinit

Although MIT-MAGIC-COOKIE-1is designed to be used with XDMCP,you can use the xauth
program directly to use the magic cookie with an X sessionstarted with xinit.
You have to do some extra work in order to use user-based access control with xinit, how-
ever. When using security on the console display server, xdm is nice enough to generate a
unique magic cookie code for you, put it in $HOME/.Xauthority, and then start up the X
server with the -auth $HOMEi.Xauthorityoption. This tells a R4- or R5-compatible server to
look in $HOMEI.Xauthority for the magic cookie code that xdm just put there. If you're start-
ing X with xinit, you have to do this work yourself.
The first thing you need to do is to generate a magic cookie code and place it in .Xauthority.
To create the magic cookie code, you need to generate a "random" number (or at least one
that's hard to guess). If you have perl installed on your system, you can use perl's random
number generator,as in the following:
randomkey=xperl -e 'srand; printf int(rand(lOOOOOOOOOOOOOOOO))'"

or (for a more robust script):

randomkey="perl -e 'for (1..10) {
srand(time+$$+$seed);
printf(n%4.41xn/ ($seed = int(rand(65536))));
}
print n\nn;'"

The Korn shell (ksh) also has a built-in random number generator,so you can do something
like:

randomkey=vksh -c 'echo $(( $RANDCM * $RANDOM * 2 ))'"

Using standardUNIX tools, you can start with somenumber that will be different every time
(such as the processID of the .xserverrc shell, or the output of the date command), and then
convert it into something unrecognizable. Just using date (if your date command supports
this syntax), you might do something like:
randomkey=" date +" %y%m%d%H%M%S""

Using the processID, you might disguise it by passing it through the be command:
randomkey=vecho "{obase=16;$$^3}" I be"

Whichever method you use, apply the key to xauth to add it to the .Xauthority file:
randomkey=x your favorite random number generation schemehere"
xauth add ${HOST}/unix:0 . $randomkey
xauth add ${HOST}:0 . $randomkey

Security 81
 The add keyword to xauth tells it to add the given code for the given server into the
Xauthority file. Note that you needtwo entries: the first adds the key for the server under the
IPC name of unix: 0, and the second adds the key for the server under the TCP/IP name
hostname: 0. If you accessyour server as localhost: 0, you might want to add an entry
for that too. (See Section 2.3.1 for information on display names.) Note that the screen num-
ber that is often found in display names is omitted, since accesscontrol for a given server
covers all screens for that server.

The lone period (.) in the xauth command line signifies that the default protocol, MIT-
MAGIC-COOKIE-1, should be used.

Once you have added the new code to $HOME/.Xauthority,you need to start up the X server
using the code. For example:
% xinit -- /usr/bin/Xll/X -auth $HOME/.Xauthority

If you'd like xinit to do all of this automatically, you can combine the steps into your
.xserverrc file:

#!/bin/sh

# Get hostname
HOST="hostname"

# Create new magic cookie key

randomkey=" perl -e 'srand; printf int(rand(lOOOOOOOOOOOOOOOOO))'"

# Add new magic cookie key into .Xauthority

xauth add ${HOST}/unix:0 . $randomkey
xauth add ${HOST}:0 . $randomkey

# Start the X server with authorization turned on

exec /usr/bin/Xll/X -auth $HOME/.Xauthority

4.2.4 xauth vs. xhost

User-based accesscontrol is overridden by host-based accesscontrol. For example, if you

add the host ruby to the list of hosts that are allowed accessto your server,every user on ruby
will be able to accessyour server regardlessof whether you use user-basedaccesscontrol as
well. For that reason,you generally want to make sure that no hostsare listed on your access
control list. If you enablexauth-type user-basedaccesscontrol, you should confirm that host-
basedaccesscontrol is set up to restrict accessfrom all hosts.
% xhost
access control enabled, only authorized clients can connect
harry.ora.com
ruby.ora.com
opal.ora.com

As shown above, three hosts are allowed accessto your server. That means that any user-
basedaccesscontrol you have enabled is close to pointless. If you have hosts specified in the
/etc/XO.hostsfile, you need to remove hosts from that file. You can also remove hosts you
have addedto the accesscontrol list with xhost + by using xhost -:

82 X WindowSystemAdministrator'sGuide
 % xhost -
access control enabled, only authorized clients can connect

To verify that all accessfrom all hosts has beendisallowed, call xhost with no arguments:
% xhost
access control enabled, only authorized clients can connect

Now, only clients with accessto the magic cookie in $HOMEI.Xauthority can connect to your
server.

Some X terminals that support the magic cookie scheme also support host-basedaccesscon-
trol, and allow you to enable or disable it via the setup menu. This can be confusing. You
might think that you want to disable host-based accesscontrol (since you'll be using user-
basedaccesscontrol). However, disabling host-basedaccesscontrol may effectively allow all
hosts accessto your server,equivalent to doing an xhost +. For theseX terminals, you want to
enable host-based access control, but make sure that the access control list is empty. To make
sure the accesscontrol list is empty, you may have to explicitly place an xhost - in your
.xsessionscript for X terminals supporting both host-basedand user-basedaccesscontrol.

Access Control and Commercial X Servers

Most X terminals and PC X servers support XDMCP, but that doesn't necessarily mean
that they support MIT-MAGIC-COOKIE-1. You should contact the manufacturer or
consult the documentation to determine if the server uses the magic cookie. Many
serversrunning on X terminals and PCs also provide their own accesscontrol features,
mostly host-basedaccess,although some (like MacX) can be configured so that any cli-
ent requesting access to the server needs to be approved on the display. How this fits
into user-basedaccesscontrol is dependenton the manufacturer.

4.3 The XDM-AUTHORIZATION-1Mechanism (R5)

X11R5 provides two new schemesfor display accesscontrol: XDM-AUTHORIZATION-1and

SUN-DES-1.These are designed to be used in place of MIT-MAGIC-COOKIE-1,and are more
secure than MIT-MAGIC-COOKIE-l since they encrypt the authorization code as it is
transferred across the network.

The XDM-AUTHORIZATION-1 method of access control is similar to MIT-MAGIC-COOKIE-1.

The advantageit gives is that it usesDES (Data Encryption Standard)encryption, so it can-
not be "snooped" over the network.
Because of export restrictions, xdm is built without the DES encryption code enabled by
default, and hence without XDM-AUTHORIZATION-1support. To be able to support XDM-

Security 83
 AUTHORIZATION-1, you need to build xdm with the implementation of DES in
mitlliblXdmcplWraphelp.c* You should also make sure that the HasXdmAuth build flag is
set to YES. SeeSection A.2 for information on how to ftp a file.
Once you are sure that xdm supportsXDM-AUTHORIZATION-1,you can enable it on the local
display server by simply redefining the Display-Manager ._0 . authName resourcein the
xdm-config file. (By default, the MIT-MAGIC-COOKIE-1mechanism is used.) The autho-
rize resource must also be turned on.

DisplayManager*authorize: true
DisplayManager ._0. authName: XEM-AUTHORIZATION-1

Note that we only redefined the authName resourcefor the local display, : 0. At this writ-
ing, no X terminals support this mechanism.! The authName resource actually acceptsa
list of authorization schemeswhich xdm will use in order, so you could also just set the fol-
lowing global resource:
DisplayManager*authName: XEM-AUTHORIZATION-1 MIT-M&GIC-COOKIE-1

After the xdm-config file is reread by xdm, xdm will use XDM-AUTHORIZATION-1for the
local display server. As with MIT-MAGIC-COOKIE-1,the server is started with the -auth
option and the code is placed in the .Xauthority file. In this case,however, the code consists
of two parts, a 56-bit encryption key and 64 bits of random data.
Once you log in using xdm and XDM-AUTHORIZATION-1,check that you're using access
control properly with xauth list:
eap % xauth list
nugget .west.ora.com:0 XEM-AUTHORIZATION-1 bd4dc546c869a81f00979e36956f6c95
nugget/unix:0 XEM-AUTHORIZATION-1 bd4dc546c869a81f00979e36956f6c95

Note that XDM-AUTHORIZATION-1is only available for X sessionsthat are managedby xdm.

4.4 The SUN-DES-1Mechanism (R5)

The SUN-DES-1server accesscontrol schemeuses the Data Encryption Standard (DES) for
encryption of authorization data. This schemeuses Sun's SecureRFC to passauthorization
data across the network, and it uses NIS to maintain a database across the network. DES
code has export restrictions, so it may not appearon systemsoutside of the U.S.
Since SUN-DES-1uses Secure RFC, you need to have Secure RFC installed before you can
use it. SecureRFC, in turn, requires NIS (Network Information System).

* If this file does not appearin your distribution but you can legally use it, you can get it via ftp from ex-
port.lcs.mit.edu.Theprocedure is a little convoluted;seethefile publRS/xdm-auth/README for informationonhow
to obtain and incorporate the DES code.
t If the X terminalsinitiatethe connectionusingXDMCP,theywill ignoretheauthName resourceanyway.Thisre-
source is only used for X servers that are listed in the Xservers file. When the XDMCP connection is initiated from
theserverside,xdmuseswhateverauthorizationmechanismtheserverspecifiesat initiation.

84 X WindowSystem Administrator'sGuide
 SUN-DES-1gives you true user-basedaccess control. Unlike the magic cookie and XDM-
AUTHORIZATION schemes, the entire mechanism does not rely on the security of the
Xauthority file. You have to explicitly use the xhost command to add specific usersto the list
of users who can accessyour display. This gives you a degree of specificity that is unavail-
able under the other schemes.

4.4.1 Public Key Encryption

Before you can set yourself up to use SUN-DES-1,you need to understanda little about how
Secure RFC works.

Secure RFC is a system that usesboth a public key and a private key. It usesa principal to
identify an instance of a user. The principal is composedof the word unix combined with a
user ID and the name of the current NIS domain:

unix. <uid>@<NIS domain>

If the NIS domain is omitted, the current domain is assumed. If you do not know your user
ID, use the ypmatch command:
% ypmatch eap passwd
eap:zVxoeuDSWpyOG:243:100:Eric Pearce:/home/eap:/bin/tcsh

The user ID is the third field of the passwd entry. In this example, our user ID is 243. If you
need to learn the NIS domain name, use the domainnamecommand. Note that although the
NIS domain may be the same as the Internet domain, they are not related and do not neces-
sarily correspond.
% domainname
west

So in this example, the principal for user eap in the current domain would be:
unix.243@west

Or, since the current domain is the default:

unix.243@

A special case is the principal for root. The principal for root usesthe hostnamein place of
the user ID. For example, on the machine nugget, the principal for root is:
unix.nugget @west

The principal is stored with a public key in the public key database. The public key is truly
"public"-take a look at the file letc/publickey, which is world-readable:
#
# Sun Public Key Database
#
# To add an entry to this file, an administrator should use the NIS command
# "newkey" on the Network Information Services master machine.
#
# Users can also insert their own entries into this file using the chkey
# command. Commenting out the "nobody" entry below disallows this feature,
# and chkey will only allow users to change their existing entry, not create

Security 85
 # a new one.
g
nobody C3d91f44568fbbefada50d336d9bd67bl6e7016f987bb607:7675cd9b8753b5db09da
bfl2da759c2bd!331c927bb322861fffb54bel3f55e9
unix.243@west 348088b7430e213d8a253d2959cecb927b9b26c829c30a43:c6eb324ed85de
e5f47d936f81d4e!98504482e9dc415389ebabl848555b38e76
unix.206@west 18ebefbOee5fdcfa6ea6deab6fef48b0495064ea39f4f86b:6471489f26949
4cabefcc8924f8d26343dd5a89a81bc3e9a6bcfa30cc85604e3

This file contains a list of principals and public keys. It is maintained in the NIS map pub-
lickey.byname. You can look at it on NIS clients using ypmatch:
% ypmatch unix.243@west publickey.byname
348088b7430e213d8a253d2959cecb927b9b26c829c30a43:c6eb324ed85dee5f47d936f81d4
el98504482e9dc415389ebabl848555b38e76

Each user of the public key systemhas an entry in this file.

The SUN-DES-1scheme generatesa private key using the public key and your login pass-
word. In order to use the SecureRFC system,you must createa public key at least once. The
public key can be createdby an unprivileged user using the chkey command,or by root using
the newkeycommand. The private key is generatedevery time you log in and type your pass-
word. If you can log in without typing a password (via .rhosts or /etc/hosts.equiv), you
should generatea private key using the keylogin command.

4.4.2 Prerequisites for Using SUN-DES-1

Before you can use SUN-DES-1,you have to meet a seriesof requirements.

" In recent versions of SunOS, the DES code is not included in the base operating system
and must be added by the administrator. If you are not sure if you have the encryption
software, try looking for the crypt command. Systems with Secure RFC should have
crypt installed:
% which crypt
/bin/crypt

Systemswithout the DES software do not have crypt installed:

% which crypt
crypt: Command not found.

If you do not have DES installed, order the "Encryption Kit" from your OS vendor.
" You need to have built the X distribution with the HasSecureRPC flag set to YES. This
is the default for the mit/config/sun.cffile:
#define HasSecureRPC YES

" NIS must be installed and running. If you are not sure if NIS is running, try an NIS com-
mand. Systemsrunning NIS should return a hostnamefrom the ypwhich command:
% ypwhich
ruby

86 X WindowSystemAdministrator'sGuide
 Systemsnot running NIS will complain that ypbind isn't running:
% ypwhich
ypwhich: bigbird is not running ypbind

For information on NIS, see Managing NFS and NIS by Hal Stern (O'Reilly & Associ-
ates, 1991).

" The private key server, keyserv, must be running. This is usually started at system startup
in /etc/re or /etc/re.local. Usethe ps command to confirm that it is running:
% ps agx I grep keyserv I grep -v grep
74 ? IW 0:01 keyserv

" Each user of the Secure RFC system should have a unique public key entry. You can
have each user to do this on their own using chkey:
% chkey
Generating new key for unix.243@west.
Password:
Sending key change request to nugget...
Done.

or the systemadministrator can create public keys for userswith the newkeycommand:
# newkey -u eap
Adding new key for unix.243@west.
New password:
Retype password:
Please wait for the database to get updated...
Your new key has been successfully stored away.

You can also createa new public key for root on a given host using newkey:
# newkey -h nugget
Adding new key for unix.nugget.west.ora.comSwest.
New password:
Retype password:
Please wait for the database to get updated...
Your new key has been successfully stored away.

" You must propagate the public key information from NIS clients to the NIS master when
you add or change a public key on the client. If you are running the rpc.ypupdated dae-
mon, this will be done automatically. To seeif the daemonis running:
% ps agx I grep rpc.ypupdated I grep -v grep
70 ? IW 0:00 /usr/etc/rpc.ypupdated

If you do not run rpc.ypupdated, chkey and newkey will not automatically update the pub-
lic key map on the NIS master. If you have root permission on the NIS master machine,
you can push the NIS map for publickey.bynameon the NIS mastermanually:
# cd /var/yp
# make

Security 87
 It might be easier, however, to just enable rpc.ypupdated. You can make sure it will be
enabledat the next reboot by adding it to letclrc.local:
if [ -f /usr/etc/rpc.ypupdated -a -d /var/yp/$dname ]; then
rpc.ypupdated; echo -n ' ypupdated'
fi

Or you can uncomment it from letclinetd.conf:

ypupdated/1 stream rpc/tcp wait root /usr/etc/rpc.ypupdated rpc.ypupdated

and kill -HUP inetd so it will be enabled right away:

# ps agx I grep inetd I grep -v grep
197 ? IW 2:24 inetd
# kill -HUP 197

You can use the SUN-DES-1schemeonly after you have an entry for your principal in the
NIS master's public key map. This is also true for anybody else that wants to connect to
your X server.

4.4.3 Using SUN-DES-1with xdm

Once you have confirmed that SUN-DES-1works on your machine, you can set up xdm to use
it on the local console display server the sameway you set up xdm to use XDM-AUTHORIZA-
TION-1 as shown in Section 4.3.

Make sure that the authorize resource is turned on and then redefine the Display-
Manager ._0 . authName resourcefor the local display only:
Di splayManager*authori ze: true
DisplayManager._0.authName: SUN-DES-1

When you next connect, xdm will set up the server for SUN-DES-1.After logging in, check
using xhost:
eap % xhost
access control enabled, only authorized clients can connect
eap@ (unix.243@west)
unix.nugget@west

Note that not only are you listed under the xhost list, but so is the principal for root on nug-
get, unix. nugget ©west. The first line indicates the user with user ID 243 can connect to
the server from any host within the NIS domain west. The secondline indicates that root on
nugget can connect. Don't remove the root principal from the xhost listing, since you'll need
it if you want to run any setuid clients, suchas xterm. SeeSection 4.4.6 for more information.
If you do an xauth list, you'll seethis special root principal listed again:
eap % xauth list
nugget.west.ora.com:0 SUN-DES-1 unix.nugget©west
nugget/unixrO SUN-DES-1 unix.nugget@west

xdm is run as root, and xdm is responsiblefor starting the server.Since the server is started as
root, root is considered the "owner" of the server.

88 X Window System Administrator's Guide

4.4.4 Using SUN-DES-1with xinit

As with MIT-MAGIC-COOKIE-1,you need to do a little of the dirty work yourself if you want
to use SUN-DES-1with xinit. First we'll show the procedure by hand, and then we'll show
how to automate it using .xinitrc. This example is on a machine with a local display named
nugget. User cap has a user ID of 243, and the NIS domain name is west.
1. Start with a clean .Xauthority file:
nugget% rm -f .Xauthority

2. Create an entry for each type of connection from your host to your server. Usexauth with
SUN-DES-1, with the syntax:
xauth add <display> SUN-DES-1 unix.<uid>@<domain>

Give yourself permission to the machine using both its TCP/IP address and its IPC
address:

nugget% xauth add nugget:0 SUN-DES-1 unix.243@west

xauth: creating new authority file /home/eap/.Xauthority
nugget% xauth add nugget/unix:0 SUN-DES-1 unix.243@west
nugget% xauth list
nugget.west.ora.com:0 SUN-DES-1 unix.243@west
nugget/unix:0 SUN-DES-1 unix.243@west

3. Start the server with the .Xauthority file just created:

nugget% xinit -- -auth ~/.Xauthority

When the server is up and running, check who has accessby using the xhost command:
nugget% xhost
access control enabled, only authorized clients can connect
nugget.west.ora.com
localhost

The hosts list has the local machine listed by default, both by its hostname and by localhost.
Using the xhost command,you needto give yourself permission to your server.If you want to
be able to run xterm clients (or any other setuid clients) from the local host, you also have to
give permission to root (see Section 4.4.6 for an explanation of why root needs to be on your
accesscontrol list). You then needto remove the other entries. The syntax for giving a user
permission is:
xhost +username@domain

The domain field can be left empty if it is the current NIS domain. Give both yourself and
root permission to accessthe server. Note that when giving permission to root, you have to
use the root principal for that machine(unix. hostnameQdomain), not root@.
nugget% xhost +eap@ +unix.nugget@west
eap@ (unix.243@west) being added to access control list
unix.nugget©west being added to access control list

Security 89
Then remove permission from the entire host:
nugget% xhost -nugget.west.ora.com -localhost
nugget.west.ora.con being removed from access control list
localhost being removed from access control list

This ensuresthat only user cap in the current NIS domain and root on the host named nugget
can connect to your server.

Note that since the .Xauthority file only contains information about the principal that started
the server,the SUN-DES-1security method does not depend on the security of the Xauthority
file. Unlike the MIT-MAGIC-COOKIE-1 and XDM-AUTHORIZATION-1 methods, if other users
gain read accessto your .Xauthority file, they still can't accessyour server unless you expli-
citly grant them accesswith xhost.
To automatethis process,you needto edit your .xinitrc script.
#!/bin/sh

# Get user ID:

uid=xypmatch ${USER} passwd.byname I awk -F: '{print $3}'"
# Get hostname:
host=% hostname"
domain=v domainname"

# Get principal:
princ ipal=unix.${uid}@${domain}

# Add entries to .Xauthority file:

xauth add ${host}:0 SUN-DES-1 ${principal}
xauth add ${host}/unix:0 SUN-DES-1 ${principal}
# Add permission to self, remove permission from entire host:
xhost +${USER}@ +unix.${host}@${domain} -${host} -localhost

# Start some clients:

twm &
xterm &

When you start the server with xinit, this will set up your workstation display and prepareit
for SUN-DES-1 use.

Note that a private key is automatically generatedonly when you log in with your password.
If you log in without typing your password,you needto run the keylogin command to gener-
ate a new private key:
% keylogin
Password:

You might need to do this if you can remotely log into a machine because of entries in
$HOMEI.rhostsor /etc/hosts.equiv.

90 X Window System Administrator's Guide

4.4.5 Adding Another User with SUN-DES-1

To allow another user to connect to your host using SUN-DES-1security, you have to run
xhost to give the remote user access, and the remote user also has to run xauth to place an
entry for that serverin their .Xauthority file.
For this example, user cathyr on the host rock in the NIS domain west wants to connect to
the host nugget in the sameNIS domain, where user cap is currently running a server.
1. User eap has to give cathyr permission to accessthe server using xhost:
nugget% xhost +cathyr@
cathyr@ (unix.206@west) being added to access control list
nugget% xhost
cathyr© (unix.206@west)
eap@ (unix.243@west)
unix. nugget@west

2. User cathyr has to create an .Xauthority file entry with the server she wants to connect to
(nugget) and the principal of the user running the server:
rock% xauth add nugget:0 SUN-DES-1 unix.nugget@west

Note that this meansthat cathyr needsto know which user is running the server, and she
needs to know that user's principal. In this case, the server was started using xdm, so it
belongs to root, cathyr therefore needsto add root's principal, not cap's.
3. cathyr should now be able to connect to nuggefs X server:
ruby% xroach -display nugget.west.ora.com:0 &

Somethingwent wrong if cathyr gets the following error:

Xlib: connection to "nugget:0.0" refused by server
Xlib: Client is not authorized to connect to Server
Error: Can't open display: nugget:0

You might want to run X clients from a host in another NIS domain. The first complication is
that if you're in another NIS domain, it's harder to find out what principal to use in the xauth
command line. If the server was started with xdm, then you can use root's principal; but if
the serverwas started with xinit then you have to do someresearch.
If cathyr is in the sameNIS domain (as in the example above), she can figure out what prin-
cipal to use with only a little bit of detective work. She can just seewho owns Idevlconsole,
and use ypmatch and domainname to figure out that user's principal. If cathyr were in a
remote domain, however, she would have to be able to run a remote shell to the local host to
get that information:
ruby% rsh nugget Is -1 /dev/console
crw-w-w- 1 eap 0, 0 Sep 3 15:56 /dev/console
ruby% rsh nugget ypmatch eap passwd
eap:XZ70EUd8wjYgo:243 :100:Eric Pearce:/home/eap:/bin/tcsh
ruby% rsh nugget domainname
west

or she would be dependenton eap to tell her that information.

Security 91
 If you have accountson machinesin different NIS domains, you may want to display clients
running on the remote machine to your local server. You need to run xauth (using the local
principal) on the host you want to run client on, and you need to add yourself to the xhost list
again, using the remote domain name.On the remote machine:
ruby% xauth add nugget:0 SUN-DES-1 unix.nugget&west

And on the local machinerunning the server:

nugget% xhost +eap@east
eap@east being added to access control list

Note that when you add a user for a remote domain, xhost doesn't know that user's ID and
doesn't repeat it.

4.4.6 xterm and SUN-DES-1

A known problem with using the SUN-DES-1mechanismand setuid clients (such asxterm) is
that setuid clients use the wrong principal. Clients like xterm that are setuid to root try to
connect with the root principal:
unix.nugget@west

insteadof with the user's principal:

unix.243@

If you start your X sessionusing xdm, the root principal is given accessautomatically, so an
xterm will be able connect to the server. If you start your X sessionusing xinit, however, you
needto explicitly add root to your xhost list or you won't be able to run any xterm clients.
Note that this meansthat if you can run an xterm to your server, so can anyone else on the
same host as long as you have the root principal listed in the xhost accesslist. This also
meansthat if you want to run an xterm client from a remote host, you have to add the root
principal for that machineto your xhost list as well.
% xhost +unix.rock@ +unix.ruby^ora.com

4.4.7 Troubleshooting SUN-DES-1

The SUN-DES-1 scheme is pretty complicated compared to the other security schemes.
There's lots of potential for user errors, especially when creating entries with xauth. The dae-
mons used in the process will also cause problems if they are not set up correctly. Some
errors you may encounterare listed here with suggestionson what may have causedthem:
" If you use an incorrect passwordfor the user ID:
% keylogin
Generating new key for unix.243@west.
Password:
Invalid password.

92 X Window System Administrator's Guide

 If NIS is not running on the host (in this case,the host is rock):
Sending key change request to rock...
chkey: unable to update NIS database (11): can't communicate with ypserv
rock is down or not running rpc.ypupdated

If Imrletclkeyserv is not running, you might get any of the following errors:
Sending key change request to rock...
chkey: unable to update NIS database(7): local resource allocation failure
I couldn't generate a secure RFC authenticator to rock
The keyserver /usr/etc/keyserv must be running.
You may have to keylogin before doing a before doing a chkey.
If you do not have a key, you may need to get a system
administrator to create an initial key for you with newkey.
The system could be loaded, so you might try this again.

auth_create: Bad file number

Error: Can't open display: nugget:0.0

or:

Could not set unix.243@west's secret key

Maybe the keyserver is down?

" If you are running a (pre-R5) version of xauth that does not know about SUN-DES-1:
xauth: (argv):1: key contains odd number of or non-hex characters

" If you are running a (pre-R5) version of xhost that does not know about SUN-DES-1:
access control enabled (only the following hosts are allowed)
<unknown address in family 254>

If you run a mixed environment with R4 programs as well as R5 programs, make sure you
have the R5 versions of xauth and xhost in your path before the R4 versions. This applies not
only to MIT XI1R4 but also any commercial X distributions that are not yet updated to R5.

4.5 xterm and Secure Keyboard

The xterm client has a Secure Keyboard option that you can enable on the xterm Main
Menu. (You can accessthe Main Menu by holding down the CTRL key while pressing the
second mouse button.) This feature can be used to prevent others from reading what you
type in that window.
By enabling Secure Keyboard, xterm performs a GrabKeyboard() protocol request. Only
one client can grab the keyboard at a time, so the Secure Keyboard feature can be enabled
only temporarily; however, if you are typing a sensitive document or entering a passwordin
that xterm window, enabling Secure Keyboard ensuresthat only xterm is receiving input
directly from the keyboard. By using SecureKeyboard, you can be sure that no other client
can be snooping on what you type.

Security 93
 When you enable Secure Keyboard, the xterm window should reverse its colors. If the
colors do not reverse, then xterm was unable to grab the keyboard, and it is very possible
that your display is being snooped.
The Secure Keyboard feature provides some protection against a particular kind of snoop-
ing, but it has many drawbacks. One drawback, of course, is that it is available only using
xterm. Another is that it's a security feature that requires the user's intervention to be
enabled-like a seatbelt,it's only as effective as its users make it. Since it grabs the key-
board, it's annoying to use-you have to disable it every time you want to type in another
client window. And it doesn't protect against taking screendumpsof a display, just against
people snooping on keyboard input itself. The big thing it buys you is protection on pass-
words, since passwordsare not copied on the display. But the rest of your display is still up
for grabs.

4.6 Other Security Issues

Thus far we've only discussedsecurity issues as far as server accesscontrol is concerned.X
has many more security issues,which we discussbriefly here.

4.6.1 The Console xterm (R4 and Earlier)

The -C option to xterm gives the user a console window for the host running the xterm client.
Prior to XI1R5, any user can run an xterm -C regardlessof whether they are logged on to the
console.* Furthermore,multiple userscan each run xterm -C, and the console messageswill
simply display on whichever console window was openedlast. This meansthat the person on
the console display won't receive console messages,and will have no indication that mes-
sages are not being shown.

On some systems,a console window which has been diverted to a foreign server may also
prevent new login sessionson the console display. When an X server started with xinit shuts
down on the console, the login prompt may be diverted to the consolexterm window instead
of to the console itself.

There is also a possibility that if root is logged in on the console, users running xterm -C can
get root permission.
For all thesereasons,many systemsdo not support the -C option to xterm. As an alternative,
some systems (such as SCO Open Desktop) have each error messageappear in a separate
pop-up window on the console. For getting a diverted console window back, the following C
program may be of use:
/* This will redirect console input and
output back to /dev/console.
*/
#include <fcntl.h>

*For SunOS, you may wish to look at patch 100188-01 that addressesthis issue.

94 X Window System Administrator's Guide

 ttinclude <sys/termios.h>
main()
{
int fd;
if ((fd = open("/dev/console", 0_REWR, 0)) >= 0)
ioctl (fd, TIOCCONS, 0);
close(fd);
}

If you suspectthat the console has beenredirected, try compiling this program and running it
as root.

% cc -o console console.c
% su
# ./console

4.6.2 The Console and xdm (R5)

With Release5 of XI1, many of the concerns about console ownership have been solved. In
R5, xterm has been adjusted to allow only the owner of Idevlconsole to start up a console
window. Other users are able to run the -C option without receiving an error message, but no
console messageswill appear in their window. The R5 solution, however, requires a bit of
fiddling for workstations configured to usexdm on the consoledisplay.
When you start X using xinit, you have to first log into the console using getty and login, so
you necessarily own Idevlconsole. When you log in using xdm, however, you bypass the
getty/login mechanisms,so you have to be given ownership of Idevlconsole explicitly. For
that purpose,the default xdm configuration is altered in R5 to define scripts that are run when
a user logs in on the console and when the user logs out again. The xdm-config file specifies:
DisplayManager._0.startup: /usr/lib/Xll/xdm/GiveConsole
DisplayManager._0.reset: /usr/lib/Xll/xdm/TakeConsole

(The _0 meansthat this resourceis used only for xdm sessionson the display named : 0, i.e.,
the console display. SeeChapter 3 for more information on configuring xdm.}
Both the GiveConsole and TakeConsolescripts are specified as display-specific resourcesfor
the local console display. The GiveConsole script is specified with the Display-
Manager ._0 .startup resource, which defines a program that is run when the user has
first logged in, but before any other clients are executed.The TakeConsolescript is specified
with the DisplayManager ._0 .reset resource, defining a program run after the user
logs out but before a new connection is established. Both scripts are executed as root.
Although all three files are currently shell scripts, they can be any executable file. (Note that
since thesescripts are run as root, you should be extremely careful should you chooseto edit
them.)

The GiveConsole script in the R5 distribution does a simple chown to give the user owner-
ship of Idevlconsoleso that the user might get console messages:
#!/bin/sh
# Assign ownership of the console to the invoking user
#
# By convention, both xconsole and xterm -C check that the

Security 95
 # console is owned by the invoking user and is readable before attaching
# the console output. This way a random user can invoke xterm -C without
# causing serious grief.
#
chown $USER /dev/console

Similarly, the TakeConsolescript returns ownership of Idevlconsole to root:

#!/bin/sh
# Reassign ownership of the console to root, this should disallow
# assignment of console output to any random users's xterm
#
chmod 622 /dev/console
chown root /dev/console

Together, GiveConsole and TakeConsole ensure that the user running xdm on the local
display servercan receive console messages.

4.6.3 Hanging the Server Remotely (R3)

In XI1 Release3, there's a bug where the server looks for a small packet from the client
before it determines whether or not the client is in the xhost list. The server halts operation
until this packet is sent. You can find out if your X serverhas this problem by running:
% telnet localhost 6000

(6000 is the TCP/IPport used by server0 on the local host.)

If your X server freezes,then your workstation has this problem. Some servers will time out
after 30 seconds, but others will remain blocked until the telnet connection is closed. Note
that since this freezes your server, it's better not to try this from a window on your local
display!

4.6.4 Reading the Framebuffer (Sun Workstations)

Sun workstations have a special device called aframebuffer, representedby the file Idevlfb.
The framebuffer contains the current image on the console. Sun workstations supply com-
mands, called screendump and screenload, for copying the framebuffer to a file and display-
ing that file, respectively. If someonecan log onto your Sun workstation, they can usually
read your framebuffer regardlessof any X security you have in place. To view the screenon
one Sun workstation from another,try:
% rsh host screendump | screenload

From any X server,you can use the public domain xloadimage client:
% rsh host screendump I xloadimage

To prevent this, you could try changing the permissions on the framebuffer (i.e., chmod
600 /dev/fb), but this might break other programsand interfere with the functionality of
your workstation. Another possibility might be to make the framebuffer readable by only a
special group and have all commands that accessit setgid to that group, similar to how per-
mission to Idevlkmem is restricted to the kmem group.

96 X Window System Administrator's Guide

 The best solution is to use the file letc/fbtab to control accessto the frame buffer. Uncom-
ment the line that lists the frame buffer:

/dev/console 0600 /dev/fb:/dev/bwoneO:/dev/bwtwoO

and log out completely from the system and then log back in. The frame buffer device will
now be owned and only readable by you, preventing another user from reading it. As long
your account remains secure, your frame buffer should also. Seethe manual page forfbtab
for more information.

4.6.5 Removing Files in /tmp

Another trick for disrupting the server on a workstation is to remove the files in
ItmplXll-unix. This directory contains a UNIX socket file for each X server running on that
workstation.

% Is -I /tmp/.Xll-unix
srwxrwxrwx 1 littui 0 Apr 27 09:46 XO

This file is the socket descriptor used by X to connect to local server : 0 via IPC. And by
default, everyone has write permission (and thus delete permission) to ItmplXll-unix. So
another trick for perverseusersis to delete the XOfile on someoneelse's workstation.
% rsh harry rm /trap/.Xll-unix/XO

The workstation will subsequentlybe unable to use IPC to start local X clients anymore. That
is, clients will not be able to connect using the display name unix: 0 . 0 or : 0 . 0, but only
via TCP/IP or DECnet.

To protect against the XO file being deleted, turn on the sticky bit for the ItmplXll-unix
directory on systemsthat support that functionality:
root# chmod 1777 /tmp/.Xll-unix

This will prevent usersfrom deleting files that belong to other usersin that directory.
While you're there, you might want to make sure the sticky bit is set for /tmp itself. But note
that setting the sticky bit for I tmp does not set it recursively-you needto explicitly set it for
ItmplXll-unix as well.

On some versions of SunOS, cron automatically removes files in /tmp, including the
XI1-unix/ subdirectory. On those systems,change the cron job to exclude sockets by adding
"! -type s "to the find command line.

4.6.6 The Network Design

Despite all the work in keeping others from interfering with your serveror snooping on your
work, the basic security problem is in the very design of XI1: if the client and serverare run-
ning on different machines, then they necessarily communicate over the network. This
means that anyone who knows the X protocol and who knows how to snoop over TCP/IPcan
follow everything you do over the network, and none of the security mechanismsdescribed

Security 97
 in this chapter can prevent them from doing that. The X protocol itself can be encrypted,but
not without a substantial loss in efficiency.

Since new clients are started all the time, the magic cookie code itself is being sent over the
network repeatedly-so even that can be captured, and the snoop will then have direct
accessto your display. X11R5 makes DES (Data Encryption Standard) available with both
XDM-AUTHORITY-1and SUN-DES-1,so that the magic cookie is encrypted across the net-
work; but commercial servers are slow to incorporate DES code, and there are export restric-
tions on DES that make it unavailable outside of the United States.

Several X vendors have implemented the U.S. Government specification on Compartmented

Mode Workstations (CMW), which allows the X workstation to run as a standalone trusted
system.On a CMW, for example, each window has its own security label. (See the Nutshell
Handbook Computer Security Basics by Deborah Russell (O'Reilly & Associates, 1991) for
more information on security labels and trusted systems.) As you would imagine, however,
all bets are off on a networked environment. There are trusted networking specifications
being worked on (such as MaxSix), but X still has a long way to go before it can be consid-
ered secure.

4.7 Related Documentation

"Issues in Building Trusted X Window Systems," by Jeremy Epstein and Jeffrey Picciotto,
published in The X Resource,Issue 0, O'Reilly & Associates,Inc., Fall 1991.
The Xsecurity, xauth, xhost, xterm,fbtab, andxdm manual pages.

"Framework Generic Requirements for X Window System Security, Issue 1," by Maria
Cangelosi and Charles Blauner, published by Bell Communications Research, Inc.
(Bellcore), document number FA-STS-001324,July 1992.
For more information on Secure RFC, seeManaging NFS and NIS by Hal Stern (O'Reilly &
Associates, 1991).

98 X Window System Administrator's Guide

 Font Management

The fonts used by an application need to be available to every server that

might display it. This chapter discusses the issues with using fonts, installing
new fonts, and converting fonts from other formats. It also discusses the
X11R5 font server.

In This Chapter:
Fonts on the X Window System 101
xlsfonts 103
xfd 103
xfontsel 104
The Font Path 105

The Font Directory File 106

The fonts.scale File (R5 only) 107
Wildcards 108
Aliases 108
The FILE_NAMES_ALIASAlias 109
All About Fonts 110

Bitmap Versus Outline Fonts 110

Font Formats 111
Format Conversion Tools 112
Adding New Fonts 114
Adding a Single Font 114
Adding Multiple Fonts 115
Multiple Font Example 116
Problems with Running Vendor-specific Clients 117
DECWindows Examples 118
Aliasing 119
DECWindows Conversion 120
AlXWindows Example 121
OpenWindows Example 123
 Aliasing 124
OpenWindows Conversion 125
Converting from X11/NeWS to PCF or SNF 125
More Conversions 126
Providing Fonts Over the Network 127
The R5 Font Server 127
The Configuration File 128
Installing the Font Server 130
Testing By Hand 131
Changing BSD Boot Files 131
Changing System V Boot Files 132
Changing AIX Boot Files 133
Font Server Name Syntax 133
Debugging the Font Server 134
Font Server Clients 135
The Font Path and the Font Server 136
Hostname Aliases 138

A Font Server Example 138

Related Documentation . ..140
 5
Font Management

The number of fonts available under XI1 is enormous, and there's no limit to adding more.
Each size and orientation is treated as a different font. Furthermore, fonts are stored in sev-
eral different formats, so the samefont might be storedfive different ways.
The administrator's role is to ensure that each server can accessthe fonts it needsfor a given
application. In Release 3 and Release 4, fonts for servers needed to be available
locally-usually stored on a local disk drive or made to appear local via a NFS or AFS
filesystem. In Release5, fonts can be obtained either locally or through afont server, which
allows access to fonts on more than one host on the network.

5.1 Fonts on the X Window System

In general, a client has default fonts chosen by the programmer, but administrators or users
may want to changethem to their own preference. The default fonts may be too small to read,
unavailable for a given server, or just plain ugly. For example, the default font for xterm is
usually the font fixed, a 13-pixel semi-condensedfont that tends to be quite small on high-
resolution monitors.

Before we discussthe administrative issues of fonts, let's talk about how fonts are designated
on the X Window System. An example of a font name and its componentsis shown in Figure
5-1.

The field nameshave the following meanings:

Foundry This is a registered name for the font "foundry" (usually a company name)
that supplied the font to the X Consortium ("Adobe," "Bitstream," etc).
Family The "family" or typographic style of the font ("Courier," "Lucida," etc).
Weight The typographic weight or "blackness" of the font ("medium," "bold," etc).
Slant The "posture" of the typeface ("Roman" is upright, "Italic" is slanted, etc).

Font Management 101

 horizontal
resolution
(dpi)

foundry weight set width pixtIs spacing characterset

\ \ \
-b&h-lucida-medium-r-normal-sans- 1£;- 180-75-75-p- 106-iso8859- 1
T
font family slant additional vertical
style resolution
(dpi)

points averagewidth
(in tenthsof a point) (in tenthsof a pixel)

Figure 5-1. Components of a font name

Set Width The horizontal width of the font ("Normal," "Narrow," etc).

Additional Style An additional style that expressesinformation not presentin the other fields
("sans," or not specified).

Pixel Size A height measurementin pixels at a certain point size and resolution.
Point Size The size of the font in typographic "points" (1/72 of an inch).
Horizontal and Vertical Resolution

The horizontal and vertical resolution in dots per inch (dpi) from when the
font was originally designed.
Spacing The description of how the width affects placement of adjacent characters.
A proportional ("p") font's characters vary in width, so some characters
may appear closer to each other. This is usually desirable for hardcopy,
such as book. A "CharCell" ("c") font treats each character as a little box
of the same dimensions as all the other characters. These are better suited
for "terminal" displays, such as in an xterm window, which would look ter-
rible if the characterswere of varying size.
Average Width The averagewidth of the font in tenths of a pixel.
Character Set and Encoding
The encoding standard to which the font conforms to (ISO is the Interna-
tional StandardsOrganization) and the particular character set.
The fields that are usually the most important to the X administrator are:
" The size and resolution (for controlling the size of the font on the screen).
" The spacing (for use with terminal emulators).

102 The X Window System Administrator's Guide

 Fonts are specified to a client either as a resourceor with the -fn option. For example, a user
can put the following line in a resourcefile:
xterm*font: -misc-fixed-bold-r-normal-15-140-75-75-c-90-iso8859-l

or invoke xterm with the following command line:

% xterm -fn -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso8859-l

The default resourcesfor most clients are specified in their application defaults file. SeeSec-
tion D.I.2 for more information on where resources are defined.

There are several clients that deal directly with fonts. Thesecan be used to find and list all
the fonts available from the X server.

5.1.1 xlsfonts

To see all the fonts a X server knows about, run the xlsfonts command, xlsfonts acceptswild-
cards within the font specification and will list all the matching names.For example:
% xlsfonts -fn '-dec-*-*-*-*--*-*-*-*-*-*-*-*'
-dec-terminal-bold-r-normal-14-140-75-75-c-80-dec-dectech
-dec-terminal-bold-r-normal-14-140-75-75-c-80-iso8859-l
-dec-terminal-medium-r-normal-14-140-75-75-c-80-dec-dectech
-dec-terminal-medium-r-normal-14-140-75-75-c-80-iso8859-l

Note that only a small subsetof the available fonts is appropriate for the xterm client. Only
character cell fonts (with -c- in the llth field) are recommended for use in xterm windows.
Although mono-spaced-m- fonts like Courier and Lucida Typewriter can be used for xterm
most of the time, some "garbage" charactersmay occasionally appearif you use those fonts,
sincemono-spacedfonts can extend outside of the character cell.

5.1.2 xfd

The xfd client will display all the charactersof a particular font. It can be used as a quick test
to make sure a font exists and looks okay. For example, the command line:
% xfd -fn -adobe-courier-bold-r-normal--14-140-75-75-m-90-iso8859-l

would yield the window shown in Figure 5-2.

Font Management 103

 -Pidobe-Courier-Bold-R-Normal- 14-140-75-75-M-90-IS08859-1

| Quit [l P:'^V P^^^]j!!^/t P?:-£*;

\
Select a character

range: 0x0020 (0,32) thru OxOOff (0,255)

upper left: 0x0000 (0,0)

j H f $ % & r ( ) A + t - " /
0 1 2 3 4 5 6 1 8 9 : r < = > ?
s A B C D E F G H I J K L M N o

p Q R S T U V w X Y Z [ \ ] A

% a b c d e f g h i j k 1 m n 0
p q r s t u V w X Y z { 1 } *v

"-
i C £ « ¥ ! § © A « - - © -

o -
+ 2 3 V H i i o » H K % £

A A A A A A £ 9 E E E E i i I I
D N 6 6 6 6 6 X 0 U U U u Y P ft
A
a a a a a a ae 9 e e e e i i i l
b n 6 6 d 6 6 "*" 0 u u uA u Y P Y

Figure 5-2. xfd

5.1.3 xfontsel

The xfontsel client (which was new in R4) allows browsing through all the available fonts
and seeing each one in turn. When you find a font that you are happy with, click on the
"select" button and the selection can be pastedinto a file or command line without having to
type it by hand.

104 The X Window System Administrator's Guide

 quit 11select 1 namematches
-fndry-fmly-wght-slant-sU)dth-adstyl-pxlsz-ptSz-resx-resy-spc-avgUJdth-rgstry-encdng
-adobe-couriei - bold-i - normal-*-! 4-1 40-*-*-*-*-*-* _

AB CDEFGHI JKLMNOPQRSTUVWXYZ
abode fghij klmnopqrstuvwxyz
0123456789
a «9e i bn6uyA£<j:EI DHOUY

Figure 5-3. xfontsel

Consult the manual pagesfor xlsfonts, xfd, and xfontsel for more information.

5.1.4 The Font Path

The font path is a list of directories in which the server looks for fonts. On the X Window
System, fonts are usually stored in a subdirectory of lusrlliblXlIIfonts. The MIT Release4
distribution of X contains three subdirectories in lusrlliblXlIIfonts: 75dpi, 100dpi and misc.
The dpi suffix refers to the dots-per-inch or screenresolution of the display that the serveris
going to use;the misc directory contains random useful fonts for the display.
The default font path for a given server is usually set when the server is built from source
code. The typical MIT-derived local display server will come with the 75dpi, 100dpi, and
misc directories in its font path by default. You can check the current font path at any time
with the -q (query) option to the xset client. For a typical R4 server:
% xset -q
FontPath:
/usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/75<%)i/,/usr/lib/Xll/fonts/100c%)i/

Release5 includes the Speedofont directory of scalable fonts as well. (See Section 5.2.1 for
more information on Speedofonts.)
% xset -q
Font Path:
/usr/lib/Xll/fonts/misc/^usr/lib/Xll/fonts/Speedo/^usr/lib/Xll/fonts/VScapi/,
/usr/lib/Xll/fonts/100dpi/

Each of these directories is searchedin order for a specified font. The server will use the first
match it finds when there is more than one font with the samename. Users can change the
default font path with \htfp option to the xset command.For example, to add a font directory
to the font path, you might type:
% xset +fp /usr/lib/Xll/fonts/local

This command adds the directory /usr/lib/Xll/fonts/local to the current font path. The "+fp"
option prependsa directory to the font path, while "fp+" appendsit.

Font Management 105

 % xset -q
Font Path:
/usr/lib/Xll/fonts/lcx:al,/usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/75(%)i/,
/usr/lib/Xll/fonts/1004?i/

The local directory is now searchedbefore the regular directories. If you want to redefine one
of the default fonts, you can install a new one in the local directory and the server will access
the new one instead.

Rehashing the Font Path

Each time the font path is changed,the server reads the fonts.dir andfonts.alias files in
each directory listed in the new font path. The server then maintains a list of valid font
names in memory instead of searching for a font in the filesystem every time it is
requested. If a new font is added to one of the font directories and the fonts.dir or
fonts.alias files are changed, you need to update the list of fonts known to your server
with the command:

% xset fp rehash

The rehash command tells the server that something has changed and it should rebuild
this internal list.

The xset client controls many server features. Seethe manual page for xset for more infor-
mation.

The font path can also be specified when the server is first started.For example, on the com-
mand line:

% xinit - -fp /usr/lib/Xll/fonts/local,/usr/lib/Xll/fonts/misc/,\

/usr/lib/Xll/fonts/75dpi/,/usr/lib/Xll/fonts/100dpi/

or in the Xservers file:

:0 local /usr/bin/Xll/X -fp /usr/lib/Xll/fonts/local,/usr/lib/Xll/fonts/misc/,\

/usr/lib/Xll/fonts/75cpi/,/usr/lib/Xll/fonts/100dpi/

5.1.5 The Font Directory File

When a client requests a specified font, the server searchesin each of the directories in its
font path for a file called fonts.dir, as in /usr/lib/X 11/fonts/75dpi/fonts.dir. The fonts.dir file
maps the name of the requestedfont to the filename of the font as it is stored in the filesys-
tem. If there is no match, the client reverts to its own defaults (e.g., xterm reverts to "fixed").
The fonts.dir file is neededbecausesome operating systemshave restrictions on filenames.
For example, MS-DOS,VMS, and UNIX all have restrictions on filename length or on the char-
acters used within filenames. When installing a new font, you should choose a filename for
the new font that conforms to the semanticsof your operating system. The fonts.dir file con-
tains the mapping of the font filename to the name of the font itself.

106 The X WindowSystemAdministrator'sGuide

 The fonts.dir file's presenceis required for the server to accessany fonts within a directory.
It is created by the mkfontdir command. You have to run mkfontdir every time you add or
delete a font from a directory to keep the fonts.dir file in sync with the actual contents of the
font area. (SeeSection 5.3.1 for an example of how to use mkfontdir.) Thefonts.dir file has a
simple format-the first severallines of a sampleR4 file resemblethe following:
200
courBOlO.snf -adobe-courier-bold-o-normal--10-100-75-75-m-60-iso8859-l
courBO12.snf -adobe-co\irier-bold-o-normal--12-120-75-75-m-70-iso8859-l
courB014.snf -adobe-courier-bold-o-normal-14-140-75-75-m-90-iso8859-l
courBOlS.snf -adobe-courier-bold-o-normal--18-180-75-75-m-110-iso8859-l
courBO24.snf -adobe-courier-bold-o-normal--24-240-75-75-m-150-iso8859-l

The number at the top is the number of fonts in the directory. The remaining lines are pairs
of filenames and font names. The .^/extension to filenames in this example indicates the for-
mat that the font is stored in-in this case, the Server Natural Format. (See Section 5.2.2 for
more information on font formats.) The files may also have a .Z extension, if the server sup-
ports compressedfonts.

OpenWindows-specific Features
Sun's OpenWindows has a different system for fonts (scalable F3 format), but most of
the font administration utilities parallel the MIT ones in function. The OpenWindows
file Families.list is similar in function to the fonts.dir file. It is created by the bldfamily
command,which should be run any time the contents of the font directory are changed,
in the samemanner as mkfontdir.

5.1.6 The fonts.scale File (R5 only)

In R5, the outline or scalable fonts (as described in Section 5.2.1) introduce a problem with
creating the fonts.dir file. It is difficult for mkfontdir to determine the values in the font name
fields for a scalable font. If there are scalable fonts within a font directory, a fonts.scale file
should be created by hand. When mkfontdir is run, it will create entries in fonts.dir for each
bitmap font it finds and will then appendthe contentsof the fonts.scale file.
The Speedofonts distributed with R5 come with a fonts.scale file that is installed along with
the fonts in /usr/lib/XIl/fonts/Speedo. It contains an entry for each scalablefont:
8
font0648.spd -bitstream-charter-medium-r-normal-0-0-0-0-p-0-iso8859-l
font0649.spd -bitstream-charter-medium-i-normal-0-0-0-0-p-0-iso8859-l
font0709.spd -bitstream-charter-bold-r-normal-0-0-0-0-p-0-iso8859-l
font0710.spd -bitstream-cnarter-bold-i-normal--0-0-0-0-p-0-iso8859-l
font0419.spd -bitstream-courier-medium-r-normal-0-0-0-0-m-0-iso8859-l

Font Management 107

 font0582.spd -bitstream-courier-medium-i-normal-0-0-0-0-m-0-iso8859-l
font0583.spd -bitstream-courier-bold-r-normal--0-0-0-0-m-0-iso8859-l
font0611.spd -bitstream-courier-bold-i-normal-0-0-0-0-m-0-iso8859-l

As there are no other fonts in the Speedodirectory, the contents of thefonts.scale file and the
resulting fonts.dir file are identical.

5.1.7 Wildcards

As shown in our xlsfonts example earlier, users don't have to use the full names of a font
when specifying them. Wildcards can be used to limit the amount of typing required and pro-
vide flexibility.

Users can use asterisks("*") in the font specification, such as:

% xterm -fn '-fixed-*-*-*-*--15-140-*-*-*-*-*-*'

The asteriskswill match any of the possiblevalues for a given field in the font specification.
Notice that a font name using an asterisk as a wildcard needsto be single-quoted on the com-
mand line. This is to protect the asterisksfrom being interpreted by the shell.
The first font found in the font path that matchesthe pattern is the one that is used. If you
supply the pattern to xlsfonts, you can see which fonts in your font path match the pattern:
% xlsfonts -fn '-fixed-*-*-*-*--15-140-*-*-*-*-*-*'
-misc-fixed-bold-r-normal-15-140-75-75-c-90-iso8859-l
-misc-fixed-medium-r-normal-15-140-75-75-c-90-iso8859-l

Although xlsfonts may report more than one font name, only the first font listed will be used
by a client when supplied a font name using the samewildcards. If you run xfd with the same
font pattern, the name of the first matching font is displayed at the top of the window:
-misc-fixed-bold-r-normal-15-140-75-75-c-90-iso8859-l

Using wildcards could have a surprising effect, especially when a new font is installed: if an
administrator adds a new font that is similar in name to an already existing font, users may
end up matching the new one instead of the one they thought they were requesting. Other
surprises could occur when a new version of Xll is installed, as each release has had more
fonts than the previous release,leading to new matchesto a wildcard.
Using wildcards can make an application more flexible, as it may still find a usable font if the
intended one is missing, whereas a complete font specification may cause a failure if not
matched exactly.

5.1.8 Aliases

A font subdirectory can contain a file called fonts.alias, which contains aliases for font
names. An example of an alias is the default fixed font, which is defined in fonts.alias in the
MIT distribution of X as:

fixed -misc-fixed-medium-r-semicondensed-13-120-75-75-c-60-iso8859-l

108 The X Window System Administrator's Guide

 An administrator can make it easier for users to specify fonts by defining aliases for fre-
quently used fixed-width fonts. For example, if the administrator enters the following line
into the fonts.alias file:
fb!5 -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso8859-l

Users can then call the 15-point fixed bold font with the command line:
% xterm -fn fb!5

Font aliases can be used in resource files as well, as follows:

xterm*font: fb!5

You could argue that this is a bad idea, as non-standardaliases would likely fail if you used
your resourcefiles on another server.
Aliases also add flexibility to applications, as they can be assignedto more than one font. For
example, the name lucidasans-10 is aliased in lusrllib/Xll/fontsl75dpilfonts.alias as:
lucidasans-10 -b&h-lucida-medium-r-normal-sans-10-100-75-75-p-58-iso8859-l

and in lusrlliblXll/fonts/'100dpi!fonts.alias as:

lucidasans-10 -b&h-lucida-medium-r-normal-sans-14-100-100-100-p-80-iso8859-l

Which one is used dependson which directory occurs first in the font path. In this example,
the alias creates flexibility in the resolution of the display.
Another reason to alias a file is that the font name may be inconvenient to use on the com-
mand line. The "b&h" fonts shown above contain the "&" character in the font name, which
will confuse the shell.

Under OpenWindows, the files Compat.list and Synonyms.listprovide the alias mechanism.

5.1.8.1 The FILE_NAMES_ALIAS Alias

The "magic" alias "FILE_NAMES_ALIASES" indicates that the actual filenames of the font
files, with the suffixes removed, can be used as aliases for the fonts. For example, the
DECWindows fonts all have filenames that are also valid aliaseswhen you remove the exten-
sion. If thefonts.dir file has the following entry:
terminal_widel4.snf -dec-terminal-medium-r-wide--14-140-75-75-c-120-iso8859-l

The name terminal_wide14 would be a valid alias for this font if "FILE_NAMES_ALIASES"is
present in the fonts.alias file.

This method of aliasing is being downplayed by the X Consortium, as its useencouragesnon-

standardfont names. You should not rely on this mechanismin the future.

Font Management 109

 5.2 All About Fonts

There are many different font formats in use and each vendor has made changeson its own.
The first step in resolving the problems causedby this is to identify what type of font is being
used.The next step is to find the right tool to make the font available to your application.

5.2.1 Bitmap Versus Outline Fonts

For MIT servers prior to R5, a separatefont was required for each size of the font. For
example, to display the font -b&h-lucida-bold-i-normal-sans at the point sizes of 11, 14, 17,
20, and 34, you neededa font for each:
-b&h-lucida-bold-i-normal-sans-ll-80-100-100-p-69-iso8859-l
-b&h-lucida-bold-i-normal-sans-14-100-100-100-p-90-iso8859-l
-b&h-lucida-bold-i-normal-sans-17-120-100-100-p-108-iso8859-l
-b&h-lucida-bold-i-normal-sans-20-140-100-100-p-127-iso8859-l
-b&h-lucida-bold-i-normal-sans-34-240-100-100-p-215-iso8859-l

This is simply becausethe fonts are bitmaps and are stored as such. In R5, outline or "scal-
able" fonts are also available. These are stored as a description of the outline of the font and
can be scaled by the server to any point size. Scalable fonts have been available in NeWS
servers(Sun OpenWindows and SGI X/NeWS/GL) only prior to R5. The Speedofonts in R5
are of the outline type. Outline fonts can be recognized by 0 values for the size fields in the
font name:

-bitstream-charter-bold-r-normal-0-0-0-0-p-0-iso8859-l
-bitstream-charter-bold-i-normal-0-0-0-0-p-0-iso8859-l
-bitstream-courier-bold-r-normal-0-0-0-0-m-0-iso8859-l
-bitstream-courier-bold-i-normal-0-0-0-0-m-0-iso8859-l

When the font is requested, the size fields are filled in with the desired value:
% xlsfonts -fn '-bitstreeun-charter-bold-r-normal--12-*-*-*-*-*-*'
-bitstream-charter-bold-r-normal--12-120-75-75-p-75-iso8859-l

Some advantagesto outline fonts are:

" They need only one font file per font, vastly simplifying administration and conserving
disk space.
" They are more flexible, as it may be impossible to predict all sizes that might be
requestedby usersor required by different displays.
Some advantagesto bitmap fonts are:

" They usually look better than scaledfonts, as they are tuned for each size.
" They may be faster to request,as there is no scaling overheadbefore the font can be used.

You can convert specific sizes of an outline font into a bitmap font using the font conversion
tools described in Section 5.2.3. Some vendors provide bitmap versions of outline fonts at
several common sizes to boost performance.

110 The X Window System Administrator's Guide

5.2.2 Font Formats

If you are building an XI1 distribution from MIT source, the fonts arrive with a .bdf suffix,
indicating that they are in BDF format (Bitmap Distribution Format). BDF format has been
the default format since the early releasesof X. When the standardXI1 distribution is built,
BDF font files are converted into a format suitable for your server.
If you are not building XI1 from source, the fonts are usually sentwith the individual server
(for example, on a font tape sent with an X terminal). The fonts will have another suffix,
probably .snf, indicating that they are in SNF format (Server Natural Format). In R5, fonts
default to PCF format (Portable Compiled Font), with .pcf suffixes.
Following are somecommon extensionsand what they indicate about the font:
. bdf Bitmap Distribution Format. This is the form most fonts will arrive in if the
final destination is unknown. BDF files can be converted to most of the
final formats that would be used by a server. If you want to supply someone
else with a font, use the BDF format for interchange. They are ASCII files
and can be edited with a normal text editor. The MIT server is able to read
BDF files directly, but it is not the optimal format for storage.
.snf Server Natural Format. This format is used by most MIT servers in
Releases2 through 4. Fonts are stored in a binary file and are host byte
order dependent. This meansyou cannot share fonts betweena big endian
and little endian machine in most cases. Some vendors have servers that are
smart enough to detect this and convert the font "on-the-fly." See7.4.1 for
more information on SNF fonts and byte order dependencies.
.pcf Portable Compiled Font. The PCF format was designed by DEC for use
with DECWindows. It offers some advantagesover SNF, in that it is host
byte order independent.This meanshosts of different byte orders can share
the same font. DEC has made this format available to the X Consortium,
and it is now the default for MIT Release5. It is also used by recent ver-
sions of IRIX on the Silicon Graphics platform.
. spd Speedo-Bitstream.These are commercial-quality outline fonts donated to
the X Consortium by Bitstream Inc. They are included in MIT Release 5.
They can be distinguished by the fact that they all have point sizes of 0, as
they are scaledto a particular point size when they are requested.
. f3b, .fb Xll/NeWS. These formats are used by Sun Microsystem's Xll/NeWS
Server and older versions of the Silicon Graphics Xll/NeWS/GL Server.
The .f3b files are scalable F3 (formerly named "Folio") format fonts. The
.fb files are F3 format fonts scaled to certain point sizes. Some of their
administration tools parallel the MIT ones and will be mentioned in con-
text.

.ps PostScript Type3. Several of thesefonts come with the Sun OpenWindows
distribution. They can be loaded into the Xll/NeWS server with the Idf
program.

Font Management 111

 Compressedfile. This extension indicates that the compressprogram has
been run on the font file. This should reduce the size of the file on disk.
Some servers(such as those from MIT) can read compressedfonts directly,
but this is not true for all implementations.

5.2.3 Format Conversion Tools

There are several commandsfor converting from one format to another, as illustrated in Fig-
ure 5-4. The following are some common examples. See the manual pages for thesecom-
mands for more information.

bdftosnf Converts BDF to SNF. This command should come with any server that
uses SNF, such as the stock MIT server Releases 2 through 4. Example
usage:

# bdftosnf myfont.bdf > myfont.snf

bdftopcf Converts BDF to PCF. This command should come with any server that
usesPCF, such as DECWindows and MIT Release5. Example usage:
# bdftopcf -o myfont.pcf myfont.bdf

dxfc Converts BDF to PCF. This command is distributed with DECWindows.

Example usage:
# dxfc myfont.bdf > myfont.pcf

snftobdf Converts SNF back to BDF. This program can be found on various anony-
mousftp sites and X sourcearchives.* Example usage:
# snftobdf myfont.snf > myfont.bdf

convertfont Converts BDF to several Xll/NeWS formats and back. This command
comes with Sun OpenWindows. Example usage:
# convertfont -f 32 myfont.bdf

SeeSection 5.3.6.3 for an example using convertfont.

fstobdf Dumps the BDF version of any font available to the font server. See Sec-
tion 5.5 for more information on the font server.

# fstobdf -a tcp/harry.ora.com:7000 -fn fixed > fixed.bdf

getbdf Dumps the BDF version of any font available to the X server. See Section
5.3.4.2 and 5.3.5 for examplesof using getbdf.
# getbdf -font 9x15 > 9x15.bdf

kOne/jp site is export.lcs.mit.edu in contriblsnftobdf.tar.Z.

112 The X WindowSystemAdministrator'sGuide

makeafb Converts F3 fonts into Adobe Bitmap Format. This is an intermediate for-
mat used when converting XI 1/NeWS fonts.
# makeafb -16 LucidaSans-Bold.f3b

Note that font files can be read by some servers in a compressedformat, so administrators
may be able to save space by compressing font files on their systems. Compression may
causesome performance loss, as the fonts will have to be uncompressedby the server when
they are read. The space savings is desirable, as you are likely to accumulate hundreds of
fonts once you get the hang of it. The fonts may turn out to be the single largest consumerof
disk spaceof all the X components.
Be aware that converting a font from one vendor's machine for use on another may be illegal,
attractive as the idea might be. There may also be restrictions on how the fonts are to be
used-for example, they may be licensed for screenuse, but not for hardcopy. Check the
copyright notices before proceeding.

Font Conversion

BDF Native
Format Format
bdftosnf

mam) > SNF

bdftopcf
*"""» N PCF
dxfc

iniBBBB)> PCF
convertfont

4- i- * > X11/NeWS
snftobdf

^""BBH SNF
getbdf
^""K- from
Xserver
fstobdf

«_. from
font
server

Figure 5-4. Font conversion utilities

Font Management 113

 5.3 Adding New Fonts

There are lots of reasonsto expand the numbersof fonts available. Some applications, espe-
cially desktop publishing packages,provide new fonts as part of their installation. Clients
that support languagesother than English are becoming commonplace and are widely avail-
able on the Internet-these clients require large numbersof new fonts to be added.

It is possible to accessfonts in your home directory by adding paths to existing font paths
with thefp option to the xset command. This is useful for testing. It also meansthat you can
have usersinstall the fonts they want in their own home directories if you don't think every-
one will want to use them.

5.3.1 Adding a Single Font

Let's step through the procedure for adding a new font in a stock MIT R3 or R4 environment.
(For an R5 environment running a font server, the font may already exist on another system
and you can just tell the font server where it is. SeeSection 5.5 for more information.)
You may come across an application that requires some non-standardfonts, say a Kanji font
for the OSF/Motif demo program hellomotif.* This font is distributed in BDF format.
1. Convert it to SNF (or whatever is appropriate for your server) with the bdftosnf com-
mand:

# bdftosnf -t k!4-l.bdf > k!4-l.snf

# bdftosnf -t rkana!4.bdf > rkana!4.snf

The -t flag indicates that these fonts are going to be displayed on a "terminal" (such as
xterm) and each character should be same size.

2. Copy the SNF files into one of the font directories. For this example, the misc directory is
a good candidate:
# cp k!4-l.snf /usr/lib/Xll/fonts/misc
# cp rkana!4.snf /usr/lib/Xll/fonts/misc

3. Rebuild Ihefonts.dir file with the mkfontdir command:

# mkfontdir /usr/lib/Xll/fonts/misc

This command will increment by 2 the number of fonts listed on the first line of the
fonts.dir file, and add two pairs of entries: the filename and the font name.
k!4-l.snf -kl4-screen-medium-r-normal-14-140-75-75-m-140-jisx0208.1983-1
rkana!4.snf -romankanal4-screen-medium-r-nonnal-14-140-75-75-m-70-jisx0201.
1976-0

The next step would be to add aliases to fonts.alias for convenience. In the hellomotif
case, the application requests the font by its full name, not by an alias-so unlessyou
intend to accessthe font from other applications, it probably isn't worth aliasing.

* OSF/Motif source can be purchased from the Open Software Foundation.

114 The X WindowSystemAdministrator'sGuide

 4. Before the server can know about the new font, the font path needsto be rehashed.Other-
wise, an error will be returned. For example, if you try to display the new font immedi-
ately with the xfd client, using the font name in the secondcolumn of the fonts.dir file:
% xfd -fn -kl4-screen-medium-r-normal--14-140-75-75-m-140-jisx0208\
.1983-1

you will get an error suchas:

Warning: Cannot convert string "-kl4-screen-medium-r-normal-14-140-75-75
-m-140-jisx0208.1983-1" to type FontStruct

For the modified fonts.dir file to be reread without restarting the server, you must run the
xset command:

% xset fp rehash

Try xfd again to verify that it worked. If xfd can display the font, it is likely to be avail-
able for any client that requestsit from your server.
Your server may cache a font, so don't expect a font to disappear immediately even if you
delete the file that contains it on disk.

5.3.2 Adding Multiple Fonts

Some applications may require that a large number of fonts be added to your local font area.
One example of this is the public domain TeX dvi file previewer xtex.* TeX is a popular
typesetting program that runs on most systemsthat are around today. A dvi file is the device-
independent output of the TeX program. The term previewer refers to a program that dis-
plays something on your screento preview what it would look like on the final output, which
is usually done on a laser printer or typesetter.
The xtex program expects a separateXI1 font to exist for each size (magsteps,for you TeX
font weenies)of each TeX font requestedby a dvi file.t In a situation like this, it is probably
worth creating a new directory in your font area for easier administration.
There are a few advantagesto breaking up the font areainto subdirectories:
" By separatingthe ''stock',' or "vanilla" environment from the "local" areas,administration
is easier. You can save a lot of time when upgrading, as you don't have to worry about
trashing all your hard work if you have distinct areasthat won't be overwritten by a soft-
ware upgrade.This concept can be applied to other areasof X, where it may be desirable
to keep files that you install in an area separatefrom the vendor-supplied files.
" Multiple subdirectoriesgive you, the administrator, control over whether or not to export
the font areas in a networked filesystem. You may want to give the font areas different
permissions, or to give a group of users and programs permission to add new fonts

*xtex can beftp'd iiomfoobar.colorado.edu. It is part of a larger package called SeeTeX.

tThe xdvi program also previews TeX dvi files, but is able to read TeX fonts directly without converting them to an
XI1 format, xdvi is available \\aftp from export.lcs.mit.edu in Icontrib.

Font Management 115

 without intervention of the system administrator. TeX programs are an example of this,
as some are able to create fonts "on-the-fly" and want to add the newly created font to a
font areaso it will be there the next time it is requested.
" By breaking fonts up into multiple directories, you also make it easier to view the direc-
tory contents.The TeX examplealone has severalhundred entries.

The disadvantagesto this approachinclude the fact that special knowledge is required by the
end users if they want to accessa font in a nonstandarddirectory (you could alleviate this
problem by providing new userswith start-up files that include these special paths).

5.3.2.1 Multiple Font Example

For the xtex example, let's createa subdirectory in the font areacalled tex. The xtex package
describes how to create the SNF files from the BDF files in the distribution.

1. Once the SNF files are created, copy the SNF files to the new directory and rebuild the
fonts.dir file:
# cp *.snf /usr/lib/Xll/fonts/tex
# cd /usr/lib/Xll/fonts/tex
# mkfontdir

If you get an error such as:

Duplicate font names cmrlO
cmrlO.snf goof.snf
mkfontdir: failed to create directory in .

then there is more than one font with the same name. In this rigged example, two .snf
files for the same font exist in a common directory. The solution would be to delete the
one you do not want from this directory.*

2. Since you are adding a new area to the font searchpath, you will need to tell the server
where to look with the xset command.

% xset fp+ /usr/lib/Xll/fonts/tex

You probably made a typo or specified an invalid pathnameif you get an error such as:
X Error of failed request: BadValue (integer parameter out of range
for operation)
Major opcode of failed request: 51 (X_SetFontPath)
Minor opcode of failed request: 0
Resource id in failed request: 0x4
Serial number of failed request: 5
Current serial number in output stream: 8

* You could also change the name of the font in the BDF file before converting it into SNF, but something is proba-
bly wrong if you are having a name conflict.

116 The X Window System Administrator's Guide

 3. Verify your current font path using the xset command:
% xset -q
Font Path:
/usr/lib/Xll/fonts/irdsc/,/usr/lib/Xll/fonts/75dpi/,
/usr/lib/Xll/fonts/100dpi/,/usr/lib/Xll/fonts/tex

Note that, in order to accessthe new fonts, usershave to run the xsetfp+ command specified
above every time they start their server. Their .xsessionor .xinitrc files would be an appropri-
ate place for the command. For sites that start their X sessionsfrom xdm, you can add local
changeslike this one to the xdm startup files. This will add the font path for all users who
start their X sessionsusing xdm.
Rather than creating multiple font directories to be addedto the font path of each server,you
could just put all non-standardfonts into one directory, for example, IusrlliblXlI/fonts/local.
Some vendor implementations (such as DECWindows) provide a "local" directory structure
just for this purpose. The path is already known to the server, so you can add fonts and they
will be available without further changes.

You could also define this path within the default searchpath when you build the XI1 distri-
bution from source (using the DefaultFontPath build flag) or supply a font path when
starting the X server. SeeSection 8.5 for information on how to change your build flags when
building XI1 from source. To supply a new font path when starting the X server, most
serversaccept a -fp option on the command line.

5.3.3 Problems with Running Vendor-specific Clients

The fonts available to a server vary from one vendor to another. If a client requests a font
from the server and it is not recognized, this may render an application unusable or just make
it look strange.
Let's say you are on a Sun running an MIT Release4 server and wish to run the DECWin-
dows desk calendar dxcalendar off a remote Ultrix host, dxcalendar looks for specific fonts
that are not available on the Sun, and the program will complain about the missing fonts:
scud% dxcalendar
X Toolkit Warning: Cannot convert string "-*-MENU-MEDIUM-R-Normal
-*-120-*-*-P-*-ISO8859-l" to type FontList, using fixed font
X Toolkit Warning: Cannot convert string "-*-Menu-Medium-R-Normal
-*-100-*-*-P-*-IS08859-l" to type FontList, using fixed font
X Toolkit Warning: Cannot convert string "-*-Menu-Medium-R-Normal
-*-120-*-*-P-*-IS08859-l" to type FontList, using fixed font

The application in this example will still run, but it doesn't look as good as it should.
The InfoExplorer utility in AlXWindows also has its own set of fonts. While InfoExplorer
will run without its fonts, you can improve its appearanceon a non-AIXWindows server by
making thesefonts available to it.

Font Management 117

 The OpenWindows cm (calendar manager) is a highly desirable program, but it, like most
OpenWindows applications, will look terrible running under the MIT R4 server if you don't
make its special fonts available. It will also complain about missing fonts:
h-street% cm
XView warning: Cannot lead font '-b&h-lucida-medium-r-normal-sans-*
-90-*-*-*-*-*-*' (Font package)
XView warning: Cannot load font '-b&h-lucida-bold-r-normal-sans*-9
0-*-*-*-*-*-*' (Font package)

For all these examples, the solution is to make the font available to the local server. (This
may cause some confusion for people new to X, as the fonts might appear to be available
along with the clients on a remote host.)
Sometimesthe solution to supplying a missing font may be as simple as creating an alias to it
from an existing font. It is also possible to convert fonts required by a special client into a
format that is recognized by your server, but this may involve some work. The getbdf pro-
gram is one such font converter that may work.* getbdf can query the server for a font and
dump it out in the W/form, which can then be converted into the local font format.
In most cases,you should do the conversion from bdf to your local format on the machine
where the fonts are going to reside. This should avoid any problems with byte order when the
conversion takes place.
The font server introduced in MIT R5 will probably eliminate theseproblems, but it will take
some time before the font server is available for all X servers. In the meantime, the tech-
niques introduced here should suffice.
These examples may not match the exact problem you are having. Think of them as "case
studies" that show problem solving techniques.The purpose of this section is to demonstrate
that it is possible for the administrator to compensatefor differences between vendor imple-
mentations.

5.3.4 DECWindows Examples

The DECWindows software contains fonts in the directory /usr/lib/Xll/fonts/decwin that do

not exist in the MIT XI1R4 release.There are two ways to get around this problem: alias the
DECWindows fonts to existing MIT fonts, or you can convert the DECWindows PCF fonts
into SNF fonts that can be used by the MIT R4 server.
For an example problem, the dxcalendar program does not look quite right without the
DECWindows fonts.

* getbdf"is available via anonymous/}/? to larry.mcrcim.mcgill.edu as X/getbdf.c.

118 The X Window System Administrator's Guide

 File Edit View Customize Help

July, 1992 ^
Wk Sun Mon Tue Wed Thu Fn Sat

27 1 2 3 4

28 5 6 7 8 9 10 11 _

29 12 13 14 15 16 17 18 u
30 19 20 21 22 23 El 25
31 26 27 28 29 30 31

" 1 o

F/gure 5-5. dxcalendar with the wrong fonts

5.3.4.1 Aliasing

In recent versions of DECWindows documentation (UWS ReleaseNotes), DEC supplies a

fonts.alias file that maps the DEC font names to reasonableMIT equivalents. The top of the
file looks like this:

-Adobe-"ITC Avant Garde Gothic"-Book-R-Normal--10-100-75-75-P-59-IS08859-l

-Adobe-Helvetica-Medium-R-Normal-10-100-75-75-P-56-IS08859-1
-Adobe-"ITC Avant Garde Gothic"-Book-R-Normal--12-120-75-75-P-70-IS08859-l
-Adobe-Helvetica-Medium-R-Normal-12-120-75-75-P-67-IS08859-1
-Adobe-"ITC Avant Garde Gothic"-Book-R-Normal-14-140-75-75-P-80-IS08859-1
-Adobe-Helvetica-Medium-R-Normal-14-140-75-75-P-77-IS08859-1

The file is rather long. It also exists on variousftp sites, if you don't want to type it in.* You
can append it to an existing fonts.alias in the 75dpi or misc directory on the host where you
run the server from:

1. In this example, the aliasesare added to the misc directory:

# cd /usr/lib/Xll/fonts/misc

2. Make a backup copy of the original fonts.alias file:

# cp fonts.alias fonts.alias.orig

3. Append the new aliases:

# cat DECwindows_on_XllR4_font.aliases » fonts.alias

4. Tell the serverabout the new fonts and try it out:

% xset fp rehash
% dxcalendar &

*Onesuchftp siteis export.lcs.mit.edu,

in contriblDECwindows_on_XllR4jont.aliases.

Font Management 119

 Rle Edit View Customize Help

July, 1992 0
Wk Sun Mon Tue Wed Thu Fn Sat

27 1 2 3 4

28 5 6 7 8 9 10 11
n
29 12 13 14 15 16 17 18

30 19 20 21 22 23 m&m 25

31 26 27 28 29 30 31

" 1
2

F/gure 5-6. dxcalendar with aliases

5.3.4.2 DECWindows Conversion

Another option is to use a program that extracts fonts from the server and outputs them in
BDF format. You can then convert them into SNF or whatever your local server requires.
Once they are in your local format, you can add them to your font directory.
1. Compile the getbdf program on the Ultrix host:
% cc -o getbdf getbdf.c -1X11

2. On the Ultrix host, run the getbdf program to dump out the fonts into BDF format. Since
fonts.alias contains the keyword FILE_NAME_ALIASES,you know that the filename of
the font is also a valid name for the font. You can use this fact to automate the conversion
process.If you are using csh, the following commandswill convert each font in the direc-
tory:

# cd /usr/lib/Xll/fonts/decwin/75dpi
# foreach goo (*.pcf)
? set foo="basename $goo .pcfx
? getbdf $foo > $foo.bdf
? end

The sh equivalent would be:

# cd /usr/lib/Xll/fonts/decwin/75dpi
# for goo in *.pcf
> do
> f00="basename $goo .pcf^
> getbdf $foo > $foo.bdf
> done

120 The X Window System Administrator's Guide

 3. Make a directory on the target machine for the new fonts:
# mkdir /usr/lib/Xll/fonts/decwin

4. Copy all the BDF files to the new directory on the target machine or accessthem via
NFS. On the target machine, convert the BDF fonts to local format (SNF in this example)
for your server. This example also usescsh:
# foreach goo (*.bdf)
? bdftosnf $goo > ^basename $goo .bdf^.snf
? end

The sh equivalent would be:

# for goo in *.bdf
> do
> bdftosnf $goo > ^basename $goo .bdf^.snf
> done

5. Create the fonts.alias file:

# echo FILE_NAMES_ALIASES > fonts.alias

6. Create the fonts.dir file:

# mkfontdir

7. Add the new directory to your font path:

% xset fp+ /usr/lib/Xll/fonts/decwin

8. Try out a program that needsDECWindows fonts:

% dxcalendar &

5.3.5 AlXWindows Example

The InfoExplorer utility on the IBM RS/6000 running AIX also has its own set of fonts. The
InfoExplorer fonts are in the directory /usr/lpp/info/X 11fonts. As in the Ultrix example, you
need to convert the fonts into BDF format and then into the native format of your server. You
can use the same font conversion trick here that we used in the DECWindows conversion. In

this example, the target serverusesthe SNF format.

1. Compile the getbdf program on the AIX host:
% cc -o getbdf getbdf.c -1X11

2. Use the getbdf program to dump the fonts into BDF format. Since thefonts.alias file con-
tains the keyword FILE_NAME_ALIASES,you know that the filename of the font is also a
valid name for the font. You can use this fact to automate the conversion process.This
example is using csh:

Font Management 121

 # cd /usr/lpp/info/Xllfonts
# foreach goo (*.snf)
? set f00="basename $goo .snf'
? getbdf $foo > $foo.bdf
? end

The sh equivalent would be:

# cd /usr/lpp/info/Xllfonts
# for goo in *.snf
> do
> f00="basename $goo . snf^
> getbdf $foo > $foo.bdf
> done

3. Make a new directory on the target machinefor the new fonts:

# mkdir /usr/lib/Xll/fonts/aixwin

4. Copy all the BDF files to the new directory on the target machine or accessthem via
NFS. You will also need thefonts.alias file from the AIX machine:
% cp /usr/lpp/info/Xllfonts/fonts.alias aixwin.alias

5. On the target machine, convert the BDF fonts to SNF format for your server. If you are
using csh, the following commandswill convert each font in the directory:
# foreach goo (*.bdf)
? bdftosnf $goo > *basename $goo .bdf*.snf
? end

The sh equivalent would be:

# for goo in *.bdf
> do
> bdftosnf $goo > "basename $goo .bdfx.snf
> done

6. Copy in the fonts.alias file:

# cp aixwin.alias fonts.alias

7. Create the fonts.dir file:

# mkfontdir

8. Add the new directory to your font path:

% xset fp+ /usr/lib/Xll/fonts/aixwin

122 The X WindowSystem Administrator'sGuide

5.3.6 OpenWindows Example

The cm desktop calendar program in the Sun OpenWindows 2.0 distribution does not work
properly under MIT R4 without the fonts it needs. To demonstratethe problem, try running
the cm program without the aliases.

May 1992
Sun

Figure 5-7. cm without aliases

The dateson the calendar are missing, becausethe necessaryfonts are missing.

Font Management 123

5.3.6.1 Aliasing

Mostof thesetypesof font problemscanbehandledby a few aliases.Aliasescanbeaddedto

an existingfonts.aliasfile, suchas the one in /usr/liblXll/fontsl75dpil. This exampleadds
the necessaryfonts to thefonts .alias file so you can run cm under an MIT R4 server. Simply
appendthe following lines to thefonts.alias file:
-b&h-lucida-medium-r-normal-sans-9-90-75-75-p-58-iso8859-l -b&h-lucida-
medium-r-normal-sans-10-100-75-75-p-58-iso8859-l
-b&h-lucida-bold-r-normal-sans-9-90-75-75-p-58-iso8859-l -b&h-lucida-
bold-r-normal-sans-12-120-75-75-p-79-iso8859-l

Next, tell the server about them:

% xset fp rehash

Now, run cm again, this time with the aliases(seeFigure 5-8.)

May 1992
Sun Won Tue Wed Thu Fri Sat
1 2

3 4 5 6 7 8 9

10 11 12 13 14 15 16

17 18 19 20 21 22 23

24 25 26 27 28 29 30

31

Figure 5-8. cm with aliases

124 The X WindowSystemAdministrator'sGuide

5.3.6.2 OpenWindows Conversion

An alternative to aliaseswould be to convert the OpenWindows XI 1/NeWS fonts into a form

usable by the MIT server.* Since this procedure is unique to OpenWindows, it deservesan
explanation.
The Xll/NeWS fonts are outline fonts that are scaled to a requestedsize before rendering.
Theseare storedwith the .f3b extension. Some examplesof the Lucida family of fonts are:t
LucidaBright-Demi.f 3b LucidaSans-Boldltalic.f3b
LucidaBright-Demiltalic.f3b LucidaSans-Italic.f3b
LucidaBright-Italic.f3b LucidaSans-Typewriter.f3b
LucidaBright.f3b LucidaSans-TypewriterBold.f3b
LucidaSans-Bold.f3b LucidaSans.f3b

There is some overhead involved in scaling a font. In order to reduce this, somecommonly
used fonts can be pre-scaled. Pre-scaledfonts have the extension .fb. Some examples for the
LucidaSans-Bold font are:

LucidaSans-BoldlO.fb LucidaSans-Boldl4.fb LucidaSans-Bold6.fb

LucidaSans-Boldl2. fb LucidaSans-BoldlS. fb LucidaSans-BoldS.fb

Thesefonts are scaledat the point sizes of 6, 8, 10, 12, 14, and 18.

5.3.6.3 Converting from X11 /NeWS to PCF or SNF

It is possible to convert the Xll/NeWS format into BDF and then into the local format for
your server.As an example, if you needa "Lucida-Sans-Bold" font in 10 point:

1. Find the pre-scaled Xll/NeWS version. It will have a .fb extension and have the point
size as part of the name:
# cd /usr/openwin/lib/fonts
# Is LucidaSanslO.fb
LucidaSans-BoldlO. fb

2. Convert the font into BDF format. The convertfont program understandsa variety of for-
mats: the -x flag tells it to output the font in BDF format. The -d flag specifies the direc-
tory where the BDF version of the font will be written and the -s flag specifiesthe point
size.

# convertfont -x -d /tmp -B 10 LucidaSans-BoldlO.fb

LucidaSans-BoldlO.fb->/tnp/LucidaSans-BoldlO.bdf

3. Convert the font into the native format of your server (in this example, SNF).
# bdftosnf LucidaSans-BoldlO.bdf > LucidaSans-BoldlO.snf

*If you have a full OpenWindows distribution, BDF versions of the Lucida fonts can be found in the directory
lusrlopenwinlsharelsrclfontsi'{100dpi,75dpi,misc). They can be convened directly to your local server format using
bdftosnf or bdftopcf.
tThe pathnames listed in this example are from OpenWindows version 3.0. In OpenWindows 2.0, the font names
are abbreviated. For example, LucidaSans-Bold in version 3.0 was LcdS-B in 2.0.

Font Management 125

5.3.6.4 More Conversions

You maywantto generatepre-scaledOpenWindowsfonts at newpoint sizes.Thesecanbe

used under the OpenWindows server or converted for use by the MIT server.
For this example,let's assumeyou wantto generatea 16-pointversionof LucidaSans-Bold.
There are severalstepsneededto do this:
1. Convert the F3 format font (fib) into an Adobe ASCE format bitmap font (.afb) at the
size you require (16). The -M flag suppressesgeneration of an Adobe ASCII format met-
ric file (.afrri)'.
# makeafb -16 -M /usr/openwin/lib/fonts/LucidaSans-Bold.f3b
Creating LucidaSans-Boldl6.afb

2. Convert Adobe ASCII format bitmap font into XI 1/NeWS format:

# convertfont -b LucidaSans-BoldlS.afb
LucidaSans-Boldl6.afb->./LucidaSans-Boldl6.fb

3. In order for the OpenWindows server to be able to use the font, you have to rebuild the
Families.list file with the bldfamily command.
# cd /usr/openwin/lib/fonts
# bldfamily
* Terminal-Bold /usr/openwin/lib/fonts/TerminlB.ff (Encoding: latin)
* Terminal /usr/openwin/lib/fonts/Terminal.ff (Encoding: latin)

* ni!2 /usr/openwin/lib/fonts/ni!2.ff (Encoding: unknown)

* k!4 /usr/openwin/lib/fonts/k!4.ff (Encoding: unknown)

Error messages such as:

cat: ./Compat.list: No such file or directory

or:

*
.... ff (Encoding: unknown)

can be ignored. The Compat.list and Synonyms.listfiles are optional, much in sameman-
ner asfonts.alias.

The font is now ready to be used by the OpenWindows server or converted to a MIT format
using the method described in Section 5.3.6.3.

126 The X WindowSystemAdministrator'sGuide

5.4 Providing Fonts Over the Network

Diskless workstations and X terminals presenta new set of problems for font administration.
For an X server to display text on a diskless workstation or X terminal, it has to have access
to fonts on a remote host, since X terminals don't have any local permanent storage.X termi-
nals will typically come with a small set of fonts (usually fixed, at the minimum) that are
stored in ROM, but need to read additional fonts over the network to be useful.

TFTP access is often needed for X terminals to boot off the remote host. When an X terminal
is initially powered up or rebooted, it broadcastsa requestfor boot servicesover the network
and a designated host downloads a kernel or server to the X terminal. See Section 7.4 for
more information on fonts and X terminals.

Fonts can also be downloaded using the same mechanism after the X terminal is up and run-
ning, but a more flexible approach is to NFS-mount the fonts from a remote host. The server
can then add fonts "on-the-fly" after booting. Unfortunately, this also implies all the normal
administration problems associatedwith NFS, such as accesscontrol, network loading, and
server failures. When using NFS, X terminals become closer to the diskless workstations that
they were designed to replace, as they are subject to the sameproblems. SeeSection 7.4.3 for
more information.

5.5 The R5 Font Server

Previous to Release 5, fonts on the X Window System needed to be available on local disk or
provided over the network via TFTP or NFS. Starting with R5, fonts can be requestedfrom a
font server.
The font server is a program that runs on a host somewhereon the network and provides fonts
to your X server. This makes font administration easier,as you can have several sourcesfor a
given font, which makes font accessmore reliable and less dependent on a single host. It
also separatesfont problems from TFTPand NFS problems.
The font server can understand several different font formats. This means that all you have
to do to make a font available is to run the font server on the host where the font resides. You
no longer have to copy over the font and convert it to a format recognized by your local
server. This is great for multi-vendor environments where you have many different font for-
mats, as clients can run under any server and are still able to accessspecial fonts they may
require.
There is a host-basedsecurity mechanismto limit font accessto a group of hosts.This can be
used when making licensed fonts available with the font server. The number of simultaneous
connections to the font server can be controlled, preventing the font server host from being
overloaded. Font requests can also be passed onto other font servers if the current one
becomes overloaded.

The font server program supplied in MIT R5 is called fs and is usually installed as
lusrlbinlXlllfs. The font server is described in the manual page for/5. If you have accessto
the MIT source code, the file mitldoc/fontserverlFSlib.doc describes the font server library

Font Management 127

 functionsandmitldoclfontserverldesign.ms
providesa detaileddescriptionof the font server
design.

5.5.1 The Configuration File

The font server's operation is controlled by a configuration file, usually named

lusrlliblxlllfslconfig. If you are building R5 from the MIT sourcecode and want to use the
font server,you may want to enable the InstallFSConf ig flag in your configlsite.de/ file.
Setting the flag to YES will copy a sample font server configuration file into
lusrlliblxlllfslconfig when the make install is performed. See Section 8.5.1 for more infor-
mation on configuring XI1 at build time.
The syntax of the configuration file is pretty simple. The following is a sample file that con-
tains every option:
# font server configuration file (kitchen sink version)
#
cache-size = 2000000
#
alternate-servers = pepper.ora.com:8000,bigbird.ora.com:8001
#
catalogue = /usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/Speedo/,
/usr/lib/Xll/fonts/75dpi/,/usr/lib/Xll/fonts/100dpi/
#
client-limit = 10
#
clone-self = on
#
default-point-size = 120
#
default-resolutions = 75,75,100,100
#
error-file = /var/log/fs
#
port = 7000
#
trusted-clients = pepper,bigbird
#
use-syslog = off
#

Any line starting with a "#" is treatedas a comment and ignored.

The following keywords are defined in the configuration file:
cache-size

This is the number of bytes of memory that the font server will allocate in its
font cache.The cachespeedsup font access,as any recentlyrequestedfont
should still be in the cache and immediately available (otherwise, it would have
to be read from a file on disk or scaledfrom an outline font). If the font serveris
runningon a hostthat haslots of memory,makethecachesizelarger.Thecache
size is approximately 2 megabytesin this example.

128 The X WindowSystemAdministrator'sGuide

alternate-servers
This is a list of alternate font servers for this font server. If the current font
server is unable to service the request, it supplies a list of alternate-
servers to the X server, permitting the X serverto try again at one of the alter-
nate font servers. The name of an alternate serveris a hostname and port number
pair separatedby a colon. The alternate servers are referred to as delegates in
the MIT documentation. The primary server will supply a client with a list of
alternate servers that it knows about. This example has two alternate servers,
one on the host pepper and the other on bigbird.

catalogue
A list of font directories available from this server.* This example lists all the
standard MIT R5 font directories. These can be stored in any format recognized
by the font server. The font server currently understandsthe PCF, Speedo,SNF,
and BDF formats, described in Section 5.2.2. This keyword should not be con-
fused with the catalogue-list component of the font server name (see Section
5.5.6 for an explanation).
client-limit
The number of clients that the font server will allow before cloning itself or
rejecting the connection. If the clone-self flag is set to off and a client attempts a
connection, the font server will send back a reply listing other font serversthat it
knows about. Theseare specified in the alternate-servers list.
clone-self
Whether the font server should attempt to clone itself or use delegates when it
reachesthe client-limit. In this example, it is set to on and the font server would
spawn another copy of itself if it received more than 10 (the client-limit} connec-
tions.

default-point-size
The default point size (in tenths of a point) for font requests that don't specify
this value. These are called decipoints in the MIT documentation. The example
value of 120 indicates a 12 point size.
default-resolutions

Default resolutions supportedby the server. The numbers are pairs of horizontal
and vertical resolutions per inch. Resolutions of 75x75 and 100x100 are speci-
fied in the example.
error-file
The filename of the error log file. You can use this if your system does not sup-
port the syslogO facility. This file would normally be the first place you would
look when debugging the font server configuration file. Leave out this keyword
if you have use-syslogenabled.

*You may notice that the syntax described here differs from the paper "Font Server Implementation Overview,"
(mitldoclfontserverldesign.ms) where a prefix of the font format, such as pcfor Speedo,is used in front of the font di-
rectory list. This feature is not used in the MIT R5 font server.

Font Management 129

 port TheTCPport numberon which thefont serverwill listenfor client connections.
Since the font server does not use a privileged port, a user can start up her own
font server at any time. As you can choosethe port number yourself, you can test
the font server without disturbing other serversby selecting a unique port num-
ber. The MIT examples all use port 7000. This is a safe distance from port 6000,
which is what the X server uses.

use-syslog
Whether syslog() is to be used for error logging. If set to on, font server errors
will be sent to the LOGJLOCALO syslog facility. You will need to add a line to
your Ietclsyslog.conf file to capture the error messagesin a file. If you log other
messagesto the directory /var/log, the following entry will add logging for the
font server:

localO.debug /var/log/fs

This will log errors to the file Ivarlloglfs. Seethe manual page on syslog.conf(5)
for more information on setting up syslog. If you want to use the error-file key-
word, set use-syslog to off.
trusted-clients
The names of hosts the font server will supply fonts to. This can be used to
restrict fonts to a certain group of hosts for licensing reasons.An empty list indi-
cates that any host can make a connection to the font server.

You probably won't need to specify most of theseoptions for your site. The MIT-supplied
configuration file lusrlliblXHIfslconfig should be good enoughto start with:
# font server configuration file
# $XConsortium: config.cpp,v 1.7 91/08/22 11:39:59 rws Exp $
clone-self = on
use-syslog = off
catalogue =
/usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/Speedo/,/usr/lib/Xll/fonts/75
dpi/,/usr/lib/Xll/fonts/100dpi/
error-file = /usr/lib/Xll/fs/fs-errors
# in decipoints
default-point-size = 120
default-resolutions = 75,75,100,100

5.5.2 Installing the Font Server

If you wishto havethefont serverrunningall thetime (asyou probablydo),you canadd it to

a systemstart-upfile, suchas IetcIre.local.However,you probablyshouldnot add it to any
systemfiles until you are satisfiedthat it will work correctly.You can testit "by hand"by
starting it on the command line.

130 The X WindowSystem Administrator'sGuide

5.5.2.1 Testing By Hand

The -config flag can be used to test a configuration file that is not yet installed or when you
do not have write permission to fusr/lib/Xll/fs'.
# fa -config ./test-config &

If the font server dies with the error:

Error: Binding TCP socket: Address already in use

Error: Fatal server error!
Error: Cannot establish any listening sockets

there is probably another font server (or some other program) running with the same port
number. You can specify a number other than 7000 (the default) with the port keyword in the
configuration file or on the command line with the -port flag:
# fs -config ./test-config -port 7001 &

The SIGUSR1signal will causethe serverto reread the configuration file. Use this if you have
edited the file and wish your changesto take effect without having to kill and restart the font
server.

The SIGUSR2signal will cause the server to flush the font cache. This may be desirable if you
want the server to get a fresh copy of a font instead of using a cached version that may be
out-of-date.

The SIGHUP signal is used to reset the server, closing all active client connections and
rereading the configuration file.
You can kill the font serverat any time by sending it the SIGTERMsignal.
For example, under BSD UNIX:
# kill -TERM fs pid

Under SystemV:
# killall -TERM fs

When you are satisfied with the font server's configuration, it can then be addedto the system
boot files, which will automatically start it upon the next reboot.

5.5.2.2 Changing BSD Boot Files

In the BSD world, the /etc/re.local file is the usual place to add new daemons. You will want
to locate the entry for the font server before any other XI1-related daemons(such as xdm), if
they are going to need fonts from the font server.

For SunOS4.x, an exampleletc/rc.local entry would look like this:

#
# start up X font server
#
if [ -f /usr/bin/Xll/fs ]; then
/usr/bin/Xll/fs & echo -n ' fs'
fi
#

Font Management 131

 Under Ultrix, it would look like:
[ -f /usr/bin/Xll/fs ] && {
/usr/bin/Xll/fs ; echo ' fs' >/dev/console
}

Examine your system's startup files and mimic the other daemon entries when adding the
font server. The // or / test syntax is designed to allow the system to continue the boot pro-
cesswithout errors if the fs executableis missing.

5.5.2.3 Changing System V Boot Files

System V systemsusually have a separatefile for each daemon that is started when the sys-
tem boots. Under IRIX (the Silicon Graphics System V derivative), adding the font server
would take severalsteps:
1. Create a shell script to control the font server in letclinit.d. Check the current contentsof
this directory and pick a namefor the script that describesit (fs is a good choice):
# cd /etc/init.d
# Is
MOUNTFSYS acct bsdlpr cron nek perf uucp
REAEME audio cdromd.2 Ip netls savecore winattr
RMTMPFILES autoconfig configmsg mail network sysetup xdm

The easy way to create a new script is to copy an existing one and modify it:
# cp xdm fs
# editfile...

This script is copied from xdm and modified for the font server:
#!/bin/sh
#
# Start X Font Server
#
IS_ON=/etc/chkconfig
FS=/usr/Xl1R5/bin/f s

case "$1" in
'start')
if test -x $FS; then
if $IS_ON fs;
then
$FS &
fi
fi
/i

'stop')
/etc/killall -TERM fs

echo "usage: /etc/init.d/fs {start I stop}"

esac

132 The X WindowSystemAdministrator'sGuide

 2. Create symbolic links to letc/init.dlfs from the letc/rcO.d and Ietclrc2.d directories. The
format of the symbolic link name is either a "S" (for start) or a "K" (for kill), followed by
a sequencenumber that determines the order of the file execution, followed by the name
of the file in letc/init.d. To determine the sequencenumber,you need to see what numbers
are already in use. Here is a listing from a sampleIRIX 4.0 system:
% Is /etc/rc2.d
SOLMOUNTFSYS S30network S50mail SVOuucp S88configinsg
S20sysetup S40nck S58RMTMPFILES SVScron S95autoconfig
S21perf S45netls S601p SVSwinattr S97cdromd
S22acct S48savecore S61bsdlpr S83audio S98xdm

The S98xdm entry is for the xdm daemon. Since xdm may require the font server to be
running before it starts,you should move it to the next highest number:
# rav S98xdm S99xdm

And then make a link to the file /etc/init.d/fs file:

# In -s /etc/init.d/fs S98fs

Repeatthe processfor the letclrcO.d entry:

# Is
KIBcron K20mail K251p K30netls K40network K90sysetup
KISuucp K22acct K26bsdlpr K35nck K78winattr

In this case,there isn't a sequencenumber conflict with an existing script:

# In -B /etc/init.d/fs K98fs

3. The final step is to add an entry to the letclconfig directory to enable the script at boot
time:

# /etc/chkconfig -f fs on

5.5.2.4 Changing AIX Boot Files

AIX is a combination of SystemV and BSD. Starting the font server consistsof adding a line
to letc/rc.tcpip:
# Start font server
start /usr/bin/Xll/fs ""
#

5.5.3 Font Server Name Syntax

Any client wishing to use the font server must be supplied with the name of the host where
the font server is running and the port number that the font server is listening on. Thesetwo
componentsuniquely identify a particular instance of the font server:
transport /hostname -.port

Font Management 133

 The following are example font server names:
tcp/harry:7000
tcp/ruby.ora.com:7000
tcp/128.197.2.1:7001
tcp/fonts.ora.con:7002

The font server name can be specified on the command line with the -server option or set
with the FONTSERVER environment variable. For example:
% setenv FONTSERVER tcp/harry:7000
% fsinfo

is equivalent to:
% fsinfo -server tcp/harry:7000

5.5.4 Debugging the Font Server

The fsinfo client gives a quick way to check if the font server is running or not. In this
example, the font server is running on port 7000 on the host harry:
harry% fsinfo -server tcp/harry:7000
name of server: harry:7000
version number: 1
vendor string: MIT X Consortium
vendor release number: 5000
maximum request size: 16384 longwords (65536 bytes)
number of catalogues: 1
all
Number of alternate servers: 0
number of extensions: 0

Thefsinfo client will also display any alternate serversknown to the current server:

Number of alternate servers: 2

#0 bigbird:8001
#1 pepper:8000

If the font server is not running or if you have incorrectly specified the name of the font
server, fsinfo will fail:
harry% fsinfo -server tcp/foo:1234
fsinfo: unable to open server "tcp/f00:1234"

If youhavespecifiedthehostandport numbercorrectly,makesurethefont serverprogramis

still running. The ps command can be used to check for this.
Under BSD UNIX:

% ps agx I grep fs I grep -v grep

4237 ? IW 0:01 /usr/bin/Xll/fs

134 The X WindowSystemAdministrator'sGuide

 Under System V UNIX:
% pa -ef I grep fs I grep -v grep
root 169 1 0 Jan 2 ? 0:00 /usr/bin/Xll/fs

If the process doesn't show up, there probably is a serious error in the configuration file or
something else is wrong with your system.
If the font serverhas reachedits client limit, a connection to it may fail with:
FSlib: connection to "rock:7000" refused by server
FSlib: name of server: rock:7000
fsinfo: unable to open server "rock:7000"

Turning on the clone-self keyword or raising the client-limit are possible solu-
tions.

If you have the error-file flag specified in the configuration file, all font server error
messageswill appear in the lusrlliblXlllfslfs-errors file (or the file specified with the
error-file parameter). If the use-syslog flag is enabled, the errors will be logged in
the file specified in letc/syslog.conffor the LOG_LOCALO facility.
Any error messageprefixed with CONFIG: has something to do with the configuration file. A
typical error might be:
Error: CONFIG: can't open configuration file "/usr/lib/Xll/fs/config"

lusrlliblXlllfslconfig is the default location of the configuration file. Make sure that the file
exists and is readable. You can specify another location for the config file with the -config
option to/5. (You might use this option if you are running your own private font server.)
If you get the following error:
Error: Can't open' error file B/usr/lib/Xll/fs/fs-errors"

the font server probably does not have write permission to the error file. Any errors will be
sent to the controlling terminal or the console. You can specify a different file with the
error-file keyword in the font serverconfiguration file.

5.5.5 Font Server Clients

Once you have verified the existence of the font server, try requesting a font from it. There
are severalclients that have namesthat start with fs, indicating that they are for use with the
font server.

The fslsfonts client is analogous to xlsfonts in that it lists the namesof all available fonts or
just those specified on the command line. It understandsthe samewildcard syntax you use
when specifying fonts elsewhere.
Try a font that you know should be available from the server:
harry% fslsfonts -server tcp/harry:7000 -fn "fixed"
fixed

Font Management 135

 If you get an error, such as:
fslsfonts: pattern "goof" unmatched

the font server configuration file probably has an error in one of the pathnames,or you have
specified a non-existent font name.
The fstobdf client is used to produce a BDF version of a font requestedfrom a font server.
Using the fixed font as an example:
harry% fstobdf -server tcp/harry:7000 -fn fixed > fixed.bdf

This BDF file can then be converted to different formats for use by your server.

As the fstobdf client can be usedto "steal" fonts from another host, you might want to use the
trusted-clients parameterto restrict fonts that are licensed to specific hosts.

5.5.6 The Font Path and the Font Server

One or more font servers can be added to your font path in the samemanner as font direc-
tories. These font servers will then be searchedin the order they appear in the font path
whenever a font is requested. This is the best way to add the font server functionality to cli-
ents, as it does not require any changesin the way clients are used.
To add a font serverto your font path, just appendor prepend it to the font path as you would
do for a font directory. The syntax for naming a font serverwithin the font path is simple. For
example:
% xset fp+ tcp/harry:7000

The general syntax for TCP/IP networks is:

tcp/hostname:port-number[/catalogue-list [+catalogue-list] ]

For DECnet it is:

decnet/nodename: :font$objname[/catalogue-list[ + catalogue-list] ]

" The tcp or decnet string is the network transport or protocol usedby the font server.
" The hostname (or DECnet nodename) is the name of machine where the font server is
running.
" The port number is the port that the font server is listening on.
" The optional catalogue-list can specify a subset of the available catalogues available
from that font server. Catalogue lists are separatedby the "+" character.The term cata-
logue has two different meaningsin the font server documentation,which may be confus-
ing. The catalogue keyword in the font server config file specifiesa list of directories and
the catalogue-list in the font serveris used to divide up all the available fonts into groups
(or catalogues). The only catalogue currently supported by the font server is all. To
enablea font server to accessall the available catalogues(as you would normally want to
do), just omit the cataloguelist.

136 The X Window System Administrator's Guide

The following example has a font serverrunning on the host harry.
First, check the current font path with xset:
% xset -q
Font Path:
/usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/75c%)i/,/usr/lib/Xll/fonts/100(^i/

Add the font server entry:

% xset fp+ tcp/harry:7000

Check the new path:

% xset -q
Font Path:
/usr/lib/Xll/fonts/misc/,/usr/lib/Xll/fonts/75c%)i/,/usr/lib/Xll/fonts/1006ti/,
tcp/harry:7000

If you get the following error from xset:

X Error of failed request: BadValue (integer parameter out of range for
operation)
Major opcode of failed request: 51 (X_SetFontPath)
Value in failed request: 0x6
Serial number of failed request: 5
Current serial number in output stream: 8

either you made an error in the font server name, or the font server specified in the font path
is no longer running.
Here are somemore examplesof valid font path entries:
tcp/harry:7000
tcp/aixfonts:8000,tcp/decfonts:7000
DECnet/SRVNOD::FOttT$DEFAULT
decnet/44.70::font$special/symbols

Font path additions can specified anywhere you would normally put them, such as in a user's
.xsession or .xinitrc file:

xset m 2 2
xset b 10 100 10
xset fp+ tcp/decfonts.ora.com:7000
xrdb $HOME/.Xdefaults
xmodmap $HOME/.xmodmaprc
twm &

This example assumesthe font server will be running before the user's X sessionis started.If
it is not running, the xset command will fail with the BadValue error shown previously.

Font Management 137

5.5.7 Hostname Aliases

Usinga hostnamealias suchasfonts.ora.com

is a cleverway to simplify font administration
for a groupof hosts.The namecouldbe movedto anotherhostwithout requiringconfigura-
tion changesto the hosts that are requestingthe fonts.
/etc/hosts On a host using /etc/hostsjust add the alias to /etc/hosts:
140.186.66.2 rock.ora.con rock decfonts decfonts.ora.com

NIS If you areusingNIS, theentry will haveto beaddedon theNIS masterfor the
NIS domain. Add an entry similar to the one described above and push the
NIS hosts map.

DNS On a host running DNS, add the following alias to the name server database:
decfonts IN CNAME rock.ora.com.

and tell the name server to reload the database.

You could use a separatefont server to supply each group of fonts and have aliasesfor each
of them. For example, a decfonts alias could be for DECWindows applications, an aixfonts
alias could be for AlXWindows applications, and a texfonts alias could be used by TeX appli-
cations. Users can then select the font server according to the application and its font
requirementsregardlessof what X server they are using.

5.5.8 A Font Server Example

The xtrek game provides a good example for using the font server.* It requires a special font,
namedxtrek, that normally has to be installed for every X server that the xtrek client is going
to be displayed on. For local display servers running on workstations, this means that you
have to copy the font into a local directory on each machine and run the mkfontdir command
on every one of these hosts. A far better solution is to install the font on one host and run a
font serverthat makes the xtrek font available to anyone wanting to play.
Let's assumeyou are on the host nugget and you want to start a game on the host rock.
You try to run xtrek, but it fails, as the font is not found by nugget's server:
nugget% xtrek rock
Display: nugget:0.0 Login: eap Name: Dead Meat
Adding player 0 on "nugget:0.0'.
Not all fonts available on nugget:0.0.

To fix this problem, let's turn the host rock into a server for the xtrek font:
1. The xtrek font supplied with source code is in the BDF format. Convert the font into a
formatrecognizedby your X server.In this example,theMIT R5 serverexpectsthePCF
format:

* xtrek is available via anonymous/?/?as export.lcs.mit.edu:lcontriblxtrek.tar.Z.

138 The X WindowSystemAdministrator'sGuide

 rock% bdftopcf xtrek.bdf > xtrek.pcf

2. Copy the font into the font area. In this example, the font will have its own directory,
Ihomeleaplxtreklfonts:
rock% mkdir /home/eap/xtrek/fonts
rock% cp xtrek.pcf /home/eap/xtrek/fonts

3. Create the fonts.dir file:

rock% mkfontdir /home/eap/xtrek/fonts

4. Create a font server configuration file. The easiest way to do this is to copy and then edit
the MIT example file lusrlliblXlllfslconfig:
rock% cp /usr/lib/Xll/fs/config /home/eap/xtrek/fs-config
rock% editfile...

The edited file now contains the following:

clone-self = on
use-syslog = off
error-file = /home/eap/xtrek/fs-errors
catalogue = /home/eap/xtrek/fonts

5. Start the font server:

rock% fs -config /home/eap/xtrek/fs-config &

6. Go back to the host nugget and add the font server to the font path:
nugget% xset +fp tcp/rock:7000

7. Now try running xtrek again:

nugget% xtrek rock
Display: nugget:0.0 Login: eap Name: Dead Meat
Adding player 0 on "nugget:0.0'.

game starts successfully ...

Note that this entire procedure can be performed by unprivileged users.

Font Management 139

5.6 Related Documentation

The font clients are describedin the manpagesfor xfd, xlsfonts, andxfontsel.
The font serverclients are describedin the manpagesforfsinfo,fslsfonts, andfstobdf.
The OpenWindows font programs are described in the manpagesfor convertfont, makeafb,
bldfamily, and the OpenWindows documentationset.
A technical description of X fonts is in the file mit/doc/XLFD/xlfd.tbl.ms (the PostScript ver-
sion is mitlhardcopylXLFD/xlfd.PSZ).
For more information on the font server, seethe manpageforfs and the original design docu-
ment mitldoc/fontserver/design.ms. Beware of differences between this paper and the version
of the font server included in the R5 distribution.

The Font Server Protocol is describedin the file mitldoclfontserverlFSlib.doc (PostScript ver-
sion is mitlhardcopylFSProtocollfsproto.PS.Z).

"The X Administrator: Font Formats and Utilities," by Dinah McNutt and Miles O'Neal,
published in TheX Resource,Issue 2, O'Reilly and Associates,Inc., Spring 1992.
Section 5.5 of this chapter also appearedas an article entitled "The X Administrator: Manag-
ing Font Servers," by Eric Pearce,published in The X Resource,Issue 3, O'Reilly and Asso-
ciates, Inc., Summer 1992.

140 The X WindowSystemAdministrator'sGuide

 6

Color

This chapter describes the mechanisms used to make color available to X

servers that support color. It covers both the RGB and the Xcms methods of
color management.

In This Chapter:
Color Specification in Release 4 and Earlier 144
RGB Color Names 144
Numeric Color Values 145
Adding Your Own Color Names (RGB) 146
Fixing a Corrupted Color Database 147
Color Specification in Release 5 (Xcms) 147
Xcms Color Names 148

Adding Your Own Color Names in Xcms 150

Xcms Database Example 151
Device Profiles 152
Related Documentation . ..153
 6
Color

Color can make a world of difference for a user. Not all X users have servers that support
color, but those that do need to be able to assign colors to their applications easily. The X
Window Systemprovides a way for colors to be addressedusing both familiar names(such as
red, blue, yellow) and obscure names (such as papayawhip, pale goldenrod, and dodgerblue).
Thesenamesare then converted to a numeric representationthat the server understands.
Most color monitors are equipped with red, green, and blue electron guns, called "color
guns," as shown in Figure 6-1. Thesecolor guns can be run at different intensities, producing
different colors on the display screen. For example, the color "red" could be displayed by
turning the green and blue guns off entirely and turning the red gun on at full capacity. The
red, green, and blue gun intensity values are called an RGB triplet.

enlarged pixel

Figure 6-1. Red, green, and blue color guns

Prior to X11R5, there was no built-in mechanism to address the lack of color consistency
between displays. The mappings of RGB triplets to color nameswere hard-coded directly on
the host system, using the RGB System. This meant that when a user requested"turquoise"
on a particular system,he would get the samegun intensities regardlessof which X server he
was actually using. Since not all monitors are created equal, "turquoise" might look slightly
different depending on which display it was being viewed on. R5 addressesthis problem

Color 143
 with a new device-independent
systemcalled the X Color ManagementSystem,or Xcms.
Xcmsallowscolorsto be specifiedin internationallyacceptedstandards
that arein wide use
outside of the computer field.

Thischapterdiscusses
both theRGB andXcmssystemsof color specification.

6.1 Color Specification in Release 4 and Earlier

In Release4 and earlier, the X Window System usesthe RGB system for defining and dis-
playing different colors. MIT X11R4 defines 738 color names by associating names with
RGB triplets.

The list of colors available on your system can be retrieved using the showrgb client, or by
examining the file rgb.txt, usually in the directory lusr/liblXll or lusrlliblXlllrgb. (The con-
tents of the rgb.txt file is identical to the output of the showrgb client.) If you run the
showrgb client, be sure to use a pager, as there are screenfulsof output:
% showrgb I more
255 239 213 papayawhip
240 255 255 azure
105 105 105 dimgray
176 196 222 lightsteelblue
127 255 212 aquamarine
0 250 154 mediumspringgreen
238 232 170 pale goldenrod

Each line contains 4 columns. The first column is the red value, the second column is the
green value, and the third column is the blue value. Each value is an integer from 0 and 255,
inclusive.

The fourth column is the name assignedon your host system to that particular combination of
RGB values.

The color "black" is defined with "0" values for each color gun, and "white" is defined with
maximum values for each gun.
255 255 255 white
000 black

For a visual list of colors, try the contrib client xcolors. It will read the RGB databaseand
display all the colors it finds.

6.1.1 RGB Color Names

You can specify colors for clients by using the -fg and -bg options on the command line, or
by setting the foreground and background resourcesfor the client. For an xterm win-
dow with an aquamarine
backgroundandbluetext, for example,youcouldusethefollowing
command line:

% xterm -bg aquamarine -fg blue

144 X WindowSystemAdministrator'sGuide
 Alternatively, you could define the following resources:
xt erm* background: aquamarine
xterm*foreground: blue

To become familiar with specifying colors, try picking a few colors and passthem to a client
to see the effect. If you get an error such as:
Warning: Color name "barfgreen1' is not defined in server database

you probably chosea non-existent color or spelled a color name incorrectly.

There are several "aliases" provided for a single color-for example, the color "dark slate
grey" appearsin rgb.txt with four different ways to name it:
47 79 79 dark slate gray
47 79 79 DarkSlateGray
47 79 79 dark slate grey
47 79 79 DarkSlateGrey

All of these names produce the same color.

6.1.2 Numeric Color Values

Clearly, every RGB value cannot have a name associatedwith it, but you can also specify
colors by using the RGB values directly. Any color resource starting with the "#" character
is expected to have a number following it. The numbers are expressedin hexadecimal, with
one, two, three, or four digits for each value:
#RGB
#KRGGBB
#KRRGGGBBB
#RRRRGGGGBBBB

where "R","G", and "B" representred, green, and blue digits. For example, all of the follow-
ing color specificationsrepresentthe samevalue:
XTerm* foreground: # f 00
XTerm*foreground: #ffOOOO
XTerm*foreground: #fffOOOOOO
XTerm*foreground: #ffffOOOOOOOO
XTerm*foreground: red

You would usually produce colors with complex hex numbers only if you used a resource
editor such as OSF/Motif's mre,* props in Sun OpenWindows or the contrib client
xcoloredit,t as color names are much easier for humans to deal with.

*If you buy OSF/Motif 1.x source code from OSF, the mre program is included as "demo" program. There is a
README file, but no manpage.
txcoloredit is available via anonymous/rp from export.lcs.mit.edu as i'contrib/'xcoloredit.tar.Z.

Color 145
6.1.3 Adding Your Own Color Names (RGB)

If you come up with your own color, you can add a namefor it in the RGB database.The pro-
cedure described here requires accessto the source code for the X distribution, as the rgb
program is not normally installed along with the other X programs.
To get a hexadecimal value for the new color, you can use a color editor, such as mre, props,
or xcoloredit. When you have selectedthe color, the program will display the RGB values in
hexadecimal or write the value directly into your .Xdefaultsfile.
In the following example, the selectedcolor is a shadeof green that comesout as "b7bb6e."
The RGB databaseexpects the valuesto be in a decimal format. An easy way to convert from
hex to decimal is to use the UNIX program be:
% be

First, set the baseof input to 16 (the output defaults to base 10):
ibase=16

Then enter the numbers to be converted:

B7;BB;6E

(The be program requires the letters in the hexadecimal numbers to be in uppercase.)

be then prints out the decimal values for the three colors:
183
187
110

Type CTRL-D to exit the be program.

Once we know that our RGB triplet is (183,187,110), follow thesesteps:

1. Add the following line to the rgb.txt source file, which is located in the mit/rgb direc-
tory:*
183 187 110 UglyGreen

2. Run the rgb program using the makefile also located in the mit/rgb directory. This pro-
gram converts the text file (rgb.txt) into the UNIX dbm format (rgb.dir and rgb.pag),
which are the files actually usedas the color database:
% make
rm -f rgb.pag rgb.dir
./rgb rgb < rgb.txt

3. Then install the new rgb files in lusrlliblXll:

% make install
install -c -m 0644 rgb.txt /usr/lib/Xll
install -c -m 0644 rgb.dir /usr/lib/Xll

*If you don't havethe XI1 sourceson-line,seeAppendixF for informationon howto getthe MIT source.Youonly
haveto buildtheprogramsthatarenecessary for color management,
foundin thedirectorymit/rgb.

146 X Window System Administrator's Guide

 install -c -m 0644 rgb.pag /usr/lib/Xll
install -c -s showrgb /usr/bin/Xll
install in ./rgb done

There are a few alternate color databases that come with the source distribution in

mitlrgblothers. Examine the README file in that directory for details.

6.1.4 Fixing a Corrupted Color Database

If the color name database gets corrupted in some way (e.g., written to accidentally), the
server may not be able to find any colors with which to display. On a workstation with a
monochrome display, you may get error messagessimilar to the following:
X Toolkit Warning: Cannot allocate colormap entry for White
X Toolkit Warning: Cannot allocate colormap entry for Black
X Toolkit Warning: Cannot allocate colormap entry for white
X Toolkit Warning: Cannot allocate colormap entry for black

If you see errors of this sort, perform Steps 2 and 3 in the procedure described above. This
will overwrite the corrupted rgb database files.

6.2 Color Specification in Release 5 (Xcms)

Under the RGB triplet system,a color could look quite different due to the type of display, its
manufacturer, or the type of machine that is driving it. In Release 5, Device Independent
Color was introduced in an attempt to standardize the appearanceof colors across different
platforms.

The X Color ManagementSystem (Xcms) wasdeveloped by Tektronix, and has beenadopted

by the X Consortium for Release 5 of XI1. Since all RGB functionality is still supported,
you can treat the new color system as a supersetof the previous RGB system. If you don't
want the addedfunctionality, you can pretty much ignore it.
Under Xcms, colors are based upon internationally recognized standards(CIE)* and repre-
sent all visible colors. This differs from the RGB system, which is based upon display hard-
ware, not human vision. The Xcms system can take color values in severaldifferent formats,
called color spaces.Thesespacesdescribe color in a device-independentmanner, using terms
such as Hue (color family), Value (darkness or lightness), and Chroma (saturation or vivid-
ness). Before the values are displayed, they are modified for the particular device they are
going to be viewed on. This modification should make the color appearthe same regardless
of the manufacturer, type, or model of the display. The Xcms system should also make the
color appearthe sameon any other color device, such as a color printer equipped with Post-
Script Level 2.

*CIE stands for Commission Internationale de I'Eclairage or International Commission on Illumination.

Color 147
 A completedescriptionof the Xcmscolor modelis beyondthe scopeof this book, which
covers only the aspectsof Xcms that affect administrators.

6.2.1 Xcms Color Names

The Xcmscolor systemusesa color database on the client side,whereasthe RGB system
database
is usedby the server(seeFigure6-2). All color namesarelookedup in a Xcmscli-
ent database before being passed onto the server.

Xcmsintroducesseveralnew waysto specifycolor and retainsall of the old ones. Some

examplesof colors usedin resourcesare:
*Background: RGBi:1.0/1.0/0.0
*Foreground: NavyBlue
*Text*Background: CIElab:0.0/.54/.90
*Text*Foreground: White
*Text*border: ttffOOfc

Under the Xcms system,a color specification is checked as follows:

1. If it begins with the character "#", the rest of the color specification is interpreted as a
hexadecimal RGB value:

#<red valuexgreen valuexblue value>

This syntax is still supported,but for only backwards compatibility. You are encouraged
to use the newer uniform methods of numeric color specification.
2. If it contains the character ":", the prefix is checked to see if it is a recognized color
spaceand if it is, the rest of the color is taken as a value in that color space:
<color space>:<color space specific encoding>

The color spacesdescribedhere all use the "/" character to delimit the numeric values,
as in:

<color space>:<value>/<value>/<value>

but this method is specific to the particular encoding schemeused.

3. If it contains neither the ":" or "#" character, it is assumed to be a color name that would
appear either in the Xcms client database or the RGB server database.

The databaseis composedof pairs of color namesand correspondingnumeric color specifica-

tions. The prefix on the number indicates the type of color system that is representedby the
number. The following is a list of the current color spacesand their prefixes in the Xcms
database.

Name Prefixes

Various CIE formats CIEXYZ, CIEuvY, CIExyY, CIELab, CIELuv

Tektronix HVC TekHVC
RGB RGB

RGB intensity RGBi

148 X Window System Administrator's Guide

 Color Specification
Client Side Server Side

RGB
o> .""-> Database-
earl f
and
R4

RRB

..-^XCMSDB
-. ..-"">"
Database
-
f T
in
oc i A
''""-&" Device -;
Profile

Figure 6-2. Xcms vs. RGB color specification

Xcms stores its color database in a file called Xcms.txt, usually in lusrlliblXll. You can also
create your own Xcms databaseand setthe environment variable XCMSDBto it:
% setenv XCMSDB /home/eap/mydatabase

This will be used instead of the system database.

The databaseis similar to the rgb.txt file in that it mapsa color name to a numeric color spec-
ification, but differs in that it recognizes all the new color specification formats (color
spaces)in addition to RGB. It also supports color name aliases, as new namesfor an existing
color can be defined here. The order of the columns is also reversed compared to the RGB
database.

Here is a portion of a sample Xcms.txt file (anything outside of the lines

XCMS_COLORDB_START and XCMS_COLORDB_END is ignored.):
XCMS_O)LORDB_SrART 0.1
red CIEXYZ:0.371298/0.201443/0.059418
green CIEXYZ:0.321204/0.660070/0.159833
blue CIEXYZ:0.279962/0.160195/1.210705
aquamarine CIEXYZ:0.34672401/0.54832153/0
grayO TekHVC:0.0/0.0/0.0
graylO TekHVC:0.0/10.0/0.0
gray20 TekHVC:0.0/20.0/0.0
mygreen aquamarine
myblack black
XCMS_COLORDB_END

Color 149
 In this example,"red" is describedin CIE XYZ spaceand "grayO"in TekHVC.The name
"mygreen"is an alias for "aquamarine,"which is describedearlier in the samedatabase.
"myblack" is an alias for "black," which is in the server's RGB database.

6.2.2 Adding Your Own Color Names in Xcms

Adding a color to the Xcms databaseis very similar to adding one to the RGB database,but
there are several possible ways to describe a color. Tektronix donated a color editor, called
xtici, that allows a color to be selected in several different color spaces.*

Use the following stepsto add a new color to the color database:
1. Start the xtici program and select a color.

2. When you find one that you wish to use,click on the "Edit" button.
3. Then click on the "Copy Color ->" button. This will present a menu of three differ-
ent color spaces, as shown in Figure 6-3.

Export Edit | Help

1CopyColor ->
|HUE;
|[g Paste Color
|TekHVC
|
RGB
|VflLUE:LV«-.U
CIE u' v'Y
CHROMR:IL45.6
T~[
,i

Figure 6-3. xtici Edit menu

4. Select a color spaceand paste the value into an editor or on the command line using the
middle mouse button (or whatever button you have selected for the paste function). The
"RGB" button producesthe old-style RGB "#" format and you are better off using "Tek-
HVC" or "CIE u'v'Y."

For this example, enter these values into the Xcms.txt file in between the
XCMS_COLORDB_START
and XCMS_COLORDB_END
lines, along with a prefix of the
color space you choose (e.g., TekHVC) and a color name in the left column. Make sure

*The xtici program is not part of the normal MIT R5 distribution, but can be obtained via anonymousftp from the
host export.lcs.mit.edu as Icontriblxtici.tar.Z. A user manual is included in the doc directory in the source code for
xtici.

150 X Window System Administrator's Guide

 you use the TAB character betweenthe color name and the beginning of the color specifi-
cation. For example, to define the samecolor we createdearlier for the RGB database:
UglyGreen TekHVC:88.00004/72.66564/38.25869

5. Unlike the RGB system, you don't have to rebuild the Xcms databaseinto a binary form
after you edit it.

6.2.3 Xcms Database Example

To illustrate the use of the client-side database,let's pretend you are a clothing designer for a
mail order catalog. The marketing people have suggestedthat you chooseinteresting names
for the colors of the garments.Let's also assumethat you do not want to change any system
files, only ones in your home directory.

First, pick some nice colors using a color editor (such as xtici) and record the Xcms color
specification in a file (maybe called FallCatalog.txt). Pick catchy namesfor each color you
design and put them in the Xcms databaseformat describedearlier:
#
# Ocean's Start Fall Catalog Colors, attenpt #1
#
XCMS_COLORDB_START 0.1
Berry CIEuvY:0.34568/0.45488/0.23013
Port CIEuvY:0.37875/0.45637/0.05117
Straw CIEuvY:0.19325/0.53761/0.85767
Paprika CIEuvY:0.39617/0.51446/0.20947
GrapeFruit CIEuvY:0.19261/0.52793/0.85069
Pool CIEuvY:0.15229/0.48240/0.60646
XCMS_COLORDB_END

To test out this particular databaseby yourself, you have to tell Xcms where to look for it:
% setenv XCMSDB "/FallCatalog.txt

Let's say your clothing design program is called autoclad. You can use the color nameslisted
in the Xcms databaseas resourcespecifications:
ftutoclad*outfit1.pants: Pool
Autoclad*outfitl.tie: GrapeFruit
Autoclad*outfitl.shirt: Berry

You can also specify them on the command line:

% autoclad -fg Port -bg Paprika

If you want to try another set of colors, you can easily create another databaseand redefine
the XCMSDB environment variable to tell Xcms where to look for the new database.

Color 151
6.2.4 Device Profiles

An integralpart of Xcmsis DeviceColor Characterization(DCC),or a DeviceProfile.This

is data that tells Xcms how to modify colors to fit your particular display device so they will
look astheyshould.Thedatamaybespecificto the size,brand,model,and thetypeof screen
on which you are displaying the color.
The DCC data is stored in properties on the screen's root window. Some servers are able to
automatically load the properties with data appropriate to the attacheddisplay(s). For servers
that are built from MIT source, you will probably have to load the DCC data by hand. The
xcmsdb client that comes with the MIT source distribution will load the DCC data from a text
file you supply.

There are some sample DCC files in the directory mitlclients!xcmsdbldatafiles. Examine the
top portion of the file for a description of the monitor. This is from the file Sparcl-19.dcc:
SCREENDATA_BEGIN 0.3

NAME Sun SPARCstation 1 19" color monitor

PART_NUMBER 3
MODEL Hitachi HM-4119-S-AA-0, July 1989
SCREEN_CLASS VIDEO_RGB
REVISION 2.0

COLORIMETRIC_BEGIN
XYZtoRGB_MATRIX_BEGIN
2.898873264142915 -1.405253453722755 -0.401375502033969
-1.137294035493891 2.090468612762945 0.027097795177010
0.052401943410025 -0.208571555336254 1.027214718138772
XYZtoRGB_MATRIX_END
RGBtoXYZ_MATRIX_BEGIN
0.473564943660944 0.335917466635681 0.176180053794631
0.257273262661955 0.659599528857479 0.083127208480565
0.028079972620921 0.116792496677968 0.981397341912346
RGBtoXYZ_MATRIX_END
COLORIMETRIC_END
INTENSITY_PROFILE_BEGIN 0 3
INTENSITY_TBL_BEGIN RED 256
0x0000 0.000000000000000000
0x0101 0.000000000000000000

Oxfdfd 0.975557917109458050
Oxfefe 0.980162947219270220
Oxffff 1.000000000000000000
INTENSITY_TBL_END
INTENSITY_PROFILE_END

SCREENDATA_END

The file contains values that are loaded into the root window properties and then plugged into
Xcms functions, converting each device-independentcolor value into a device-specific value
and vice-versa. You can load a DCC file in the samemanner as you would load a .Xdefaults

152 X WindowSystem Administrator'sGuide

 file with xrdb. For example, if you have a Hitachi 19" color monitor on your Sun Spare-
Station 1, use the command:
% xcmsdb Sparcl-19.dec

As you would typically want to load the file when your server starts,your .xinitrc would be a
good place for this command:

xset m 2 2
xset b 10 100 10
xcmsdb Sparcl-19.dec
xrdb $HOME/.Xdefaults
xmodmap $HOME/.xmodmaprc
twm &

If you have the MIT XI1R5 contrib source code available, there are additional DCC files in
contriblclients/xcrtcalmonitors :

% Is
Apollol9.calOO NWP-513.calOO Sparc2-19.calOO VR290.calOO VR299.calOO
Apollol9.dcc NWP-513.dcc Sparc2-19.dcc VR290.dcc VR299.doc
Applel3.calOO SGI-PI19.calOO Sun3-60.calOO VR297-0.calOO
Applel3.dcc SGI-PI19.dcc Sun3-60.dcc VR297-0.dcc
HP98782A.calOO Sparcl-19.calOO Trinil9.calOO VR297-l.calOO
HP98782A.dcc Sparcl-19.dec Trinil9.dcc VR297-1. dec

The contrib client crtca is used to drive a colorimeter. The Tektronix J17 and Minolta

CA-100 (with low-luminance option) are colorimeters supported by this program. These
devices are used to measurea color displayed on a monitor. The output of the crtca program
is the .calOO files listed above. These are fed into the xsccd client which, in turn, produces
the device color characterization (.dec) files to be read by the xcmsdb client.
There isn't a standardlocation or naming schemeenforced for DCC files. You may have to
investigate to find what you are looking for. Keep in mind that your X display is still usable
without loading a DCC file. All you are accomplishing is color correction for your particular
display. This is extremely important for someapplications, but superfluousfor others.

6.3 Related Documentation

Seethe manpagesfor showrgb, xcolors, props, xcoloredit, and xtici.

A detailed user manual comes with the xtici source code distribution (in doc/).

The file mitldocltutorials!color .tbl.ms contains a more detailed description of color and X.
Chapter 7 of the Xlib Programming Manual, by Adrian Nye (O'Reilly & Associates, 1992).
"A Technical Introduction to the X Color Management System," by Al Tabayoyan,published
in The X Resource,Issue 0, O'Reilly and Associates,Inc., Fall 1991.

Color 153
 X Terminals

X terminals allow you to put X on everyone's desk at relatively little cost. This
chapter covers the issues with buying and configuring X terminals on your
site.

In This Chapter:
Buying an X Terminal: What's What 157
Monitors 157
Screen Size 158
Resolution 158

Depth 159
Refresh Rate 159
Keyboard and Mouse 159
X Server Software 160
Special Features 161
Memory Configuration 161
Network Interface 162
X Terminal Setup 163
Network Setup 164
Getting the IP Address Using RARP 165
Getting Information Using BOOTP 165
Trivial File Transfer Protocol (TFTP) 167
Setting Up the Network on the X Terminal 168
Debugging Hints 168
Error Messages 169
Updating the arp Table 169
Name Server Problems 169
Fonts on X Terminals 170
Font Formats 170
The Font Server (R5) 171
Choosing TFTP or NFS for Font Access 171
Reading Fonts Using TFTP 171
Reading Fonts Using NFS 172
Configuringfor the X DisplayManager 173
Configuringthe X Terminalfor xdm 173
Configuringan R5 Host 174
Configuringan R4 Host 174
Configuringxdm Without XDMCP 174
Setting Up Server Access Control 175
Remote Configurationof X Terminals 175
Remote Configurationon NCD Terminals 176
Remote Configuration on Visual Terminals 177
Remote Configuration on Tektronix Terminals 178
Reconfiguring the Host 178
Increasing the Number of Processes 178
Increasing the Number of Pseudo-ttys 179
Increasing the Amount of Swap Space 180
Swapping to a File 180
Swapping to a Disk 180
Related Documentation . ..181
 7
X Terminals

Only a few years ago, the average UNIX site was equipped with a few expensive computers,
connected to ASCII terminals on every desk. The X terminal is a newcomer in the market of
UNIX hardware. Today, the rapidly-growing market of X terminals demonstrateshow XI1
has changedthe landscapeof UNIX sites.
An X terminal is as "dumb" as an ASCII terminal, in that without a host computer to connect
to, it's nothing but a blank screen with a setup menu. But when properly configured, the X
terminal gives the user all the functionality of a workstation without all of its cost and admin-
istrative worries.

7.1 Buying an X Terminal: What's What

Today, there are more than two dozen vendors of X terminals. X terminals are sold with a
variety of screensizes, screendepth and resolution, memory configurations, and software. If
you are buying an X terminal, you'll probably want to examine recent trade magazinesfor
evaluations of current products. (The market changesso quickly that X terminals tested for
this book will undoubtedly be outdated by the time you read this.) But for background of
what you're getting into, this section describes some of the areas where X terminals differ
and how they should factor in your decision.*

7.1.1 Monitors

The monitor is arguably the single most important part of the X terminal. The size, resolu-
tion, and depth of the monitor have a bigger impact on the perceived quality of the terminal
than anything else. Accordingly, the type of monitor also has the biggest impact on the price
of the X terminal as well.

The short story is that, when choosing the monitor for an X terminal, you will end up weigh-
ing the user's needs against how much money you have to burn. A user who spendsthe day
in data-entry applications might be satisfied with a monochrome 15-inch monitor, but users

*The comp.windowsj newsgroup has a quarterly posting on X terminal manufacturers, including pricing informa-
tion.

X Terminals 157
 who do desktop publishing will probably require a 19-inch grayscale or color monitor for
viewing a two-page spread.

7.1.1.1 Screen Size

Common screensizesfor X terminals range from 14 inches to 20 inches, measuringthe diag-

onal. Some users may be made happy with a 14- or 16-inch screen, but real estate will be
cramped; if you can afford a 19-inch monitor, go for it. (Beware that the actual image area
will be smaller than the screendimensions imply; that is, a 19-inch screenwith approximate
dimensionsof 15x 12inches may have an image areacloser to 13.25x 11 inches.)
Some X terminals support a "virtual screen," whereby the screen image is actually larger
than the screen itself. The portion of the screenthat is obscured can be exposedby moving
the mouse onto that area. This may be a good compromise for some users, or it may drive
them crazy when the screenshifts every time they move the mousea bit too far.

7.1.1.2 Resolution

The resolution of a screenis usually given with its dimensions in pixels. X terminal displays
range from 640x480 pixels to 1280x 1024 pixels. A pixel is the smallest element of the dis-
play that can be addressed.The number of pixels effectively determineshow much informa-
tion can be shown on your screen.

So what does the number of pixels really tell you? If you're a purist, then you're primarily
interested in knowing how many dots per inch (dpi) there are. The best way of finding out the
dpi is to ask the X terminal manufacturer.You can try to get a reasonableapproximation by
comparing the number of pixels to the dimensions of the screen image, but you'll have to
measurethe actual dimensionsof the image (since the actual image is smaller than the screen
size).

To get an idea of what sort of resolutions should be expected,our monochrome 19-inch NCD
terminals have 1280x1024 pixels for approximately 100x100 dots per inch. Our mono-
chrome 14-inch NCD terminals have 1024x1024 pixels for 106x106 dots per inch. The
xdpyinfo client can be used to learn the dimensionsand dots per inch for any serveryou have
network accessto. Since xdpyinfo requeststhis information from the server itself, the num-
bers it reports are only as accurateas the numbers advertisedby the vendor.
Beware that for color terminals, you should concern yourself with the dot pitch of the moni-
tor as well as the resolution. The dot pitch is the distance between the dots projected by the
color guns. If the resolution of the monitor tries to display more pixels than you have dots on
the screen, the picture will be fuzzy and cause eye-strain.

Note that the higher the resolution, the more traffic over the network (since higher resolution
meansmore pixels being drawn over the network) and the more memory you'll needfor rea-
sonable performance. Low-end color and grayscale displays tend to have lower resolution
than monochrome displays, to cut down on required memory (and thus cost).

158 X Window System Administrator's Guide

7.1.1.3 Depth

The depth of an X terminal is determined by the number of bits per pixel it supportsfor color
information. A monochrome (a.k.a. static gray) monitor has one bit per pixel: each pixel is
either black or white, with no shadesof gray. Most grayscale and color monitors have 8 bits
per pixel, although somemay have as few as 2 or 4, and others may have as many as 12 or 24.
A colormonitorwith 8 bitsperpixel cansupportasmanyas28= 256simultaneous
colors;
likewise, a grayscale monitor with 8 bits per pixel can support 256 shades of gray.

If you choose to buy an X terminal with a depth of only 2 or 4 bits per pixel, beware that
some X clients are dumber than others. Some of the less robust applications assume that if
you have a depth greater than 1, then you must have 8 bits per pixel. (These clients can also
cause problems on displays with 12 or 24 bits per pixel.)

Another possible complication is that, if you buy a grayscalemonitor, you may find that some
applications think you have color. For example, on a 2-bit grayscale display, FrameMaker
will try to display windows using its color default of a blue background. The best way to
deal with this complication is to set up your application resources to use only black and
white; see Section 3.5.6 for an example of using xdm and display classesto set up different
defaults according to the display type.

Although you might be concerned that an X terminal with 8 bits per pixel may produce 8
times as much traffic as one with a monochrome display, this is seldom an issue in practice.
Most clients addressonly 1 bit per pixel, regardlessof the depth of the display.

7.1.1.4 Refresh Rate

The refresh rate of a monitor is the frequency that the screen is redrawn. If the screen is
refreshed too slowly, it may be noticeable to users and quickly cause eye-strain. In general, a
refresh rate of less than 70 Hz is considered to be too slow for daily use.

7.1.2 Keyboard and Mouse

There are several different types of keyboards available for X terminals. Since there are few
things more frustrating to users than having to use a keyboard they are unaccustomed to,
choose the keyboard carefully. DEC usersare used to different key configurations than both
Sun users and PC users. Users have different ideas of what a "UNIX" keyboard is-some
users think it's a Sun3 keyboard, others think it's a Sun4 keyboard, and some think it's a
DEC keyboard. (What NCD calls a UNIX keyboard is actually a DEC keyboard.)
Keyboards differ in things like the position of the tilde and escapekeys, the position of the
Alt key(s), and the positions of the CTRL and CAPS LOCK keys (which are sometimes
reversed, to the great frustration of the user). Most X terminal manufacturersalso have inter-
national keyboards available.
Almost all X terminals come with a 3-button mouse. The only deviations between the mouse
distributed with X terminals is whether it's a mechanical mouseor an optical mouse. Optical

X Terminals 159
 mice cost a bit more, but many people consider them to be more reliable. Trackballs are also
available from many manufacturers at an extra cost.

7.1.3 X Server Software

The X server is essentially the operating system for the X terminal. X terminals differ, how-
ever, in where the server program resides,and even where it is run.
" Many older X terminals have the X server built directly into ROM. However, these X
terminals tend to be much more expensive, and furthermore they require replacing the
ROM at every upgrade.
" Most X terminals are designedto read the X server program from a host on the network at
boot time. Upgradesinvolve replacing a single file on the host. The downside to having
the X server software loaded over the network, however, is if you intend to run X over a
serial connection-downloading a megabyte of software can take some time over a
modem line.

" Some X terminals give you the option of both-they have X server software built in, but
can then override it by downloading another server from the network. This method is cur-
rently being replaced by another method using FLASH ROM. FLASH ROM is a type of
ROM that is updated by being downloaded from a host only once. This means that you
don't have to download the entire server image every time you boot the X terminal, but
you also don't have to deal with the messiness of opening up each X terminal every time
an upgrade comes in. FLASH ROM is expensive,but it's clearly the most efficient way of
dealing with X terminal software.

" There are a few low-cost X terminals designed to run over serial lines exclusively.*
These X terminals do not actually run the X server, but rely on the host to run the X
server as well as the clients. The advantage is that all the traffic between client and
server can take place over TCP/IP or IPC, so that the communication over the serial con-
nection can be restricted to keystroke and mouseevents and to screen updates.Another
great advantageis that, since they needvery little memory to run, these serial X terminals
tend to be very inexpensive. The disadvantageis that they are still very slow (although
faster than many other methodsof running X over serial connections).

We strongly recommendthat you buy an X terminal with an XDMCP-compliantserver (R4 or

higher). (Almost all X terminals sold today support XDMCP;see Section 3.1 for more infor-
mation on XDMCP.) If you run R5 on a host, we also recommend getting an X terminal that
supports the R5 font server and (if the X terminal supports color) one that supplies color
characterization data for Xcms. (At this printing, X terminals supporting the R5 font server
and Xcms are just coming to the market.)

For the purposesof this book, we emphasizesetting up X terminals running over TCP/IPwith
the X server software downloaded over TFTP.

* These X terminals are manufactured by Graph-On and Qume. Graph-On terminals are no longer on the market.

160 X Window System Administrator's Guide

7.1.4 Special Features

As the X terminal market has grown, X terminal capabilities have expandedas well.
Local Clients Some X terminals can run X clients locally. Window managersare the most
popular clients to run locally, and can make quite an impact on perfor-
mance. Note, however, that the more you want your X terminal to do, the
more memory you'll need. And remember that the whole idea of X and the
X terminal in particular is to have cheap desktop accessto remote comput-
ing-so don't go wild on local clients unless you have real reasons for
keeping network traffic at a minimum. For example, if you're running the
X terminal over serial lines, you may want to have a local window manager.
In any event, the local window manager will be more responsive,but you
have to live with the X terminal vendor's choice of a window manager.
Backing Store Almost all X terminals are capable of backing store. Backing store allows
an X server to keep an image of obscuredwindows in memory so they can
be redrawn quickly and without network overhead when exposed. To use
this feature, however, terminals need to have some extra memory installed,
or they may produce an error message(or crash). Some terminals give the
option of using backing store only when there is enough memory available;
enable this option if it is provided with your terminal, since it might help
performance. Beware, however, that when the X terminal later needsmore
memory, it may not consider the memory set aside for backing store to be
fair game.

Remote Configuration
All X terminals can be configured using a local setup menu. Some X termi-
nals, however, also provide the ability to read their configuration parame-
ters from a file on a remote host at boot time. This becomes a great advan-
tage when you have many X terminals to maintain-it's always easier to
edit files on-line than to visit every office on your site after hours. SeeSec-
tion 7.6 for more information on remote configuration.
Peripheral Support
Many X terminals allow you to hang printers off their serial port. In addi-
tion, some X terminals made by IBM have a port for connecting a hard
drive directly to the X terminal. The hard drive is used for "swapping" large
images, reducing memory requirements.

7.1.5 Memory Configuration

X terminals rangefrom 512K of memory to 72MB. As usual, what you should get dependson
what you plan to use it for. If you plan to run graphics-intensive applications, you'll want
more memory for a reasonabledisplay. Rememberthat the more pixels on the screenand the
greater the depth of your terminal, the more memory you'll need.

X Terminals 161
 In addition,manyof the fancierfeaturesavailablefor X terminalscanbememory-intensive.
X terminals that can run clients locally will need more memory to support them. If you want
your X terminals to do backing store, that will also require more memory.
Although many X terminals are smart enough to cut down on backing store when memory
gets low, beware that some X terminals might crash if they run out of memory. If this hap-
pens,it's a good idea to disable backing store completely, if you can.
Some X terminal manufacturers use their own proprietary memory. If you think this may
turn into an issuewhen it becomestime to upgradethe memory, you might prefer to stick to a
manufacturerthat usesindustry-standardSIMMs.

7.1.6 Network Interface

Most X terminals come with built-in Ethernet and TCP/IPsupport, and most also provide a
serial interface. Some X terminals support the IBM Token Ring beneath TCP/IP.DECnet is
supported by some X terminals as well.

Most X terminals supportSLIP for running X over a modem line. X terminals supporting PPP
for modem lines are just now coming to the market. In addition, some X terminal manufac-
turers have their own serial line protocols that are more efficient than SLIP,such as NCD's
Xremote and Serial Xpress by Tektronix.

X Terminal Alternatives

There are a few alternatives to buying X terminals. If you already have PCs available,
there are many X servers that run on PCs. Although PC X servers are slower than X ter-
minals and have inferior resolution, they are often sufficient for "occasional" X users,
and can be much cheaper (depending on how "souped-up" your PC is already). See
Appendix C for more information on PC X servers.
Another alternative is to use diskless workstations instead of X terminals. New diskless
workstations are significantly more expensive than X terminals, and create more admin-
istrative overhead. But if they have enough RAM, diskless workstations are generally
faster and reduce both network traffic and the load on the central host, since all (or
most) X clients can run locally.

You can also turn an older workstation into an X terminal by installing a stripped-down
kernel running only the X server. SeeSection A. 10 for more information on how this is
done.

162 X Window System Administrator's Guide

7.2 X Terminal Setup

Assuming you now have an X terminal, you probably want to make sure it works before you
do any serious configuration. For an X terminal running over TCP/IP,this meansyou have to
perform the following steps. These steps are described in more detail later in this chapter.
Pleasenote that X terminals may have different procedureswhere noted.
1. Configure the local name server to include a new IP addressfor the new machine. If you
aren't already familiar with this procedure, seeSection A.6 for more information.
2. Install the fonts on the host machine.

The X terminal should have arrived with a font tape. Unless both the X terminal and the
host support the R5 font server (and to this date, no X terminals do), you need to install
the fonts as documented by the X terminal vendor.
Where you install your fonts dependson how you intend for them to be read. Some X ter-
minals can read fonts via NFS; all X terminals can read fonts via TFTP. Although it may
be preferable to read fonts via NFS, it's a bit harder to set up. For easy setup, therefore,
install the fonts in /tftpboot/usr/lib/XlI/vendor/fonts. (You can move the fonts elsewhere
if and when you switch to NFS.) See Section 7.4 for more information on font manage-
ment for X terminals. See Section 7.3.3 for more information on TFTP.

If the X terminal has support for the R5 font server, and you have an R5 machine running
the font server, you don't need to install new fonts. You can just set up the X terminal to
use the font server, specifying the name of the font server (consisting of transport, host,
and port number). Note that some X terminals may use the term "font server" differ-
ently-i.e., as the host that the X terminal reads its fonts from, but without actually using
the R5 font service protocol.
3. Install the X server.

If the X server is built into ROM, you can skip this step. Otherwise, the X serversoftware
was probably sent on a tape, to be copied onto the host and read by the X terminal at
startup via TFTP. Copy the X server program to the proper directory on the host machine
(probably /tftpboot) and make sure that the TFTP daemon is running on the host. (See
Section 7.3.3 for more information on TFTP.)

Next, tell the X terminal where to download the server from. At this point, you need to
consult your documentation; however, for an example, our NCD X terminals use a com-
mand line similar to the following on their boot monitors:
> bt Xncdl6 140.186.65.137 140.186.65.25

The X terminal will boot using the file ltftpbootlXncd!6 on the host with IP address
140 .186 .65.25. The X terminal will use IP address 140 .186.65.137.

After the X terminal is initially booted, you can configure its setup menu so that it can
automatically boot at power up. Alternatively, if the X terminal usesBOOTP,then you
can enter this information into /etc/bootptab; seeSection 7.3.2 for more information.

X Terminals 163
 4. Now it's time to connect to a host. If you don't have R4 or R5 xdm already running on a
host machine, see Section 3.3 for information on how to start it up.*

Once you have xdm running on a host machine, someX terminals arrive pre-configured to
do a Broadcast query. Those terminals should receive the login box immediately once the
X terminal has been supplied a broadcast address.If there's some complication, you can
configure the X terminal to query the host running xdm directly. Seeyour vendor's docu-
mentation to learn how to configure the terminal to use XDMCP.

Connecting with Telnet

If you have trouble connecting using xdm, test the connection using telnet. Most X ter-
minals are supplied with a telnet window for starting an initial client. The telnet window
may be part of the setup menu, or it may be a local X client. See your vendor's docu-
mentation to learn how to access the telnet window.

Once you have a telnet window, try to connect to a host using its IP address.If you can't
connect, there's either a cabling problem or there's something wrong with the network
configuration of the X terminal. If you can connect, log in and type "who am i" to
confirm that you're resolving to the correct hostname.Then set the DISPLAY environ-
ment variable to the hostname, and start an initial xterm.

lmui@ruby 26% who am i

rubyllmui ttyp6Aug 20 18:18 (ncd9.ora.con)
lmii@ruby 27% setenv DISPLAY ncd9.ora.com:0
lmui@ruby 28% xterm &

If the telnet session ran as a local client, the new xterm should pop up immediately. If it
ran as a subsessionof the setupmenu, you have to suspendthe setup menu to accessthe
xterm window.

If an X client can connect to your X terminal this way, then there must be something
wrong with your xdm configuration. SeeChapter 3 for more information.

7.3 Network Setup

Now for the details. To configure the X terminal for the network, you first need to set up the
hosts database.If you aren't already familiar with how to do this on your site, see Section A.6
for more information.

The hosts database maps hostnames to IP addresses. The next issue is how the X terminal
knows its IP address. Some X terminals can save their IP address in NVRAM (Non-Volatile
RAM). Other X terminals, however, have no way of storing their IP addresses.Instead,they
have to depend on the host to tell them their IP addressat boot time, using RARP (Reverse
AddressResolution Protocol) or BOOTP(Bootstrap Protocol).

*If you have configured the Xaccess file to restrict xdm accessto specified hosts, you may have to add the X terminal
to the list; see Section 7.5.2 for more information.

164 X Window System Administrator's Guide

 Another issue, for X terminals that boot over the network, is how the terminal accesses its
server binary. The server image for these X terminals resides on a host somewhere on the net-
work, and the X terminal needs to be able to read their boot image using someprotocol, gen-
erally TFTP (Trivial File Transfer Protocol).

7.3.1 Getting the IP Address Using RARP

The way RARP works is that the host machine keeps a table of Ethernet addressesand the
corresponding IP addresses.This table is kept either in I etc/ethers or in the ethers databaseif
the host usesNIS. The rarpd daemon waits for broadcastrequestsfrom X terminals and other
diskless machines. In its broadcast, the X terminal supplies its Ethernet hardware address
(which is built into their Ethernet interface). The rarpd daemon on the host respondswith its
IP address on that network.

If you don't run NIS, adding a new RARP entry is just a matter of editing /etc/ethers.
/etc/ethers has a simple syntax similar to /etc/hosts. You can get the Ethernet hardware
addressof the new X terminal from the monitor at boot time. NCD X terminals, for example,
print a messagesimilar to the following:
Boot Prom V2.1.0
Testing available memory 3 .0 Mbytes
Network controller passed 00:00:A7:10:11:BF
Keyboard controller V2.00

To add this terminal as ncd4, add the following line to /etc/ethers (convert the letters in the
hex number to lowercase):
00:00:a7:10:ll:bf ncd4

The RARP daemon uses the ethers database along with the hosts database to determine the X
terminal's IP address. Note that for RARP to work, you must have an entry for the new X ter-
minal in the hosts database.

If you run NIS, see Section A.7 for information on how to add an entry to the ethers database.

7.3.2 Getting Information Using BOOTP

BOOTPis similar to RARP,but it gives a bit more information. RARPwill tell the X terminal
only its IP address. BOOTPcan be set up to tell the X terminal its subnetmask, name server
host, and what machine and pathnameto download the X server from.
The BOOTP daemon bootpd uses a file called /etc/bootptab. The BOOTP protocol has
changed over the years, as has the syntax for bootptab. Standard BOOTP (RFC951)uses a
single-line entry per hardware address,to supply the IP addressand the name of the boot file.
The first two uncommentedlines contain, respectively, the directory in which the boot files
reside, and the default boot file. For example:
#
# default boot directory
#

X Terminals 165
 /tftpboot:/

# default bootfile
Xncdl9

# bootp clients -
# host htype haddr iaddr bootfile
ncd4 1 00:00:A7:10:11:BF 140.186.65.13 Xncdl6

The first field is the hostname of the BOOTPclient (in this example, ncd4). The secondfield
is the hardware type, with l=Ethernet. The third and fourth fields representthe hardware and
Internet addresses.The fifth field is the name of the boot file to use in the specified directory.
(The ": /" following the default boot directory /tftpboot is neededfor systemsthat run TFTP
in restricted mode.)

"Extended" BOOTP (RFC1048 with CMU extensions) has syntax similar to that of
letcltermcap and letclprintcap. A single BOOTP definition is in two parts, a "global" part
used for all machines and a part that is particular to the new machine. The "global" part must
appearfirst, and might resemblethe following:
global:\
:sm=255.255.255.0: \
:ht=ethernet:\
:ds=140.186.65.25:\
:ns=140.186.65.25:\
:to=18000:\
:hn:\
:vm=rfc!048:

The client-specific part might then resemble:

ncd4:\
:hd=/tftpboot:\
:bf=Xncd!6:\
:tc=global:\
:ha=OOOOA71011BF:\
:ip=140.186.65.13:

The two-character capabilities have the following meanings:

bf Boot file for client machine
ds IP address of Internet domain name server host
ha Hardware (Ethernet) address
hd Home directory for boot files
hn Host name

ht Hardware type
ip Internet address
ns IP address of UDP name server host
sm Subnet mask
tc Append specified entry
to Time out, in milliseconds
vm Version number of BOOTP protocol on the host
The hn entry should be set to the hostname of the terminal. For the global entry, hn
should be left blank (as shown above).

166 X Window System Administrator's Guide

7.3.3 Trivial File Transfer Protocol (TFTP)

An X terminal needs to use some simple transfer protocol to download its server software.
Most X terminals use TFTP as their transfer protocol of choice. Since TFTP does not require a
user name or password in order to allow a connection, we strongly recommend running tftpd
in "restricted" or "secure" mode. Using restricted TFTP, the server code must be copied to
the TFTP home directory-usually /tftpboot-and the X terminal needsto be told which host
to boot from. When the X terminal connects to the host via restricted TFTP, the host's TFTP
server does a chroot to /tftpboot and reads files relative to the new root.
The TFTP server is usually run from inetd, which is started at boot time from /etc/re or
rc.local. inetd managesseveral daemonslisted in letclinetd.conf', requests for those services
are routed through inetd, which then starts up the appropriate daemon.
TFTP is often disabled from inetd.conf becauseit is considered a potential security hole. If
you're not sure if TFTP is active, first make sure that inetd is running, and if it is, then look in
the configuration file for inetd (either letclinetd.conf or Ietclservers} to make sure TFTP is
called. In letclinetd.conf, the line starting TFTP should look something like the following:
tftp digram udp wait root /usr/etc/in. tftpd in.tftpd -s /tftpboot

In /etc/servers, it should look like:

tftp udp /usr/etc/in.tftpd -s /tftpboot

(The -s option says to run TFTP in "secure" mode, so that machines connecting via TFTPcan
read files only in /tftpboot. On somesystemsthis option appearsas -r, for "restricted" mode.
Since TFTP is such a security hazard, we do not recommend using it except in restricted
mode; otherwise, anyone on the network can get any file on your host!)
You can also test if TFTP is running by trying it manually:
lmui@reno % tftp ruby
tftp> status
Connected to ruby.ora.com.
Mode: netascii Verbose: off Tracing: off
Rexmt-interval: 5 seconds, Max-timeout: 25 seconds
tftp> get Xncdl6
Received 846244 bytes in 8.4 seconds
tftp>

(After quitting TFTP and confirming that the file was properly retrieved, you probably want to
remove it from the directory it was copied to.)
Test if TFTP is running in restricted mode by requesting a file that isn't in /tftpboot:
tftp> get /etc/motd
Error code 1: File not found
tftp>

Another possible error messageon somesystemsis:

tftp> get /etc/motd
Transfer timed out.
tftp>

X Terminals 167
 If you don't get an error messageand TFTP lets you copy letc/motd to your current directory,
then it isn't running in restricted mode, and you should probably be worried about what other
files can be transferred (such as letclpasswdl).
If TFTP is not enabled, edit inetd.conf or /etc/servers as appropriate, and send a SIGHUPto
inetd. This will force inetd to reread I etc I inetd.conf.
# vi /etc/inetd.conf
(restore the TFTP line)
# ps agx I grep inetd
188 ? IW 5:06 inetd
5922 q6 S 0:00 grep inetd
# kill -HUP 188

For more information on inetd, see the Nutshell Handbook, TCP/IP Network Administration,
by Craig Hunt (O'Reilly & Associates, 1992).

7.3.4 Setting Up the Network on the X Terminal

If you're using BOOTP,you don't need to do anything on the X terminal end to get the termi-
nal to connect properly to the host with the right IP addressand download its boot file. Other-
wise, however, you needto do somefiddling on the setup menu.
As far as TCP/IPis concerned,the things you needto tell the X terminal are:
" The X terminal's IP address

" The subnet mask on the network

" The name server address

" The IP address of the host to boot from

" The broadcast address

Each X terminal vendor has its own way of specifying this information in a setupmenu. See
your vendor's documentation for more information.

One bit of advice about configuring X terminals: rememberthat many X terminals needto be
explicitly told to savecurrent settingsin NVRAM, or changeswill not take effect after the X
terminal is booted.

7.3.5 Debugging Hints

If you think you've done everything right, but the X terminal still can't seemto boot, hereare
some hints.

168 X Window System Administrator's Guide

7.3.5.1 Error Messages

The X terminal itself may have a diagnostic window for reporting error messages.The diag-
nostic window is the first place to look for errors. If all the "interesting" information scrolls
off the screentoo quickly, you may be able to limit the level of diagnostic information by set-
ting a lower error messagelevel via the setup menu; see your vendor's documentation for
details.

If the X terminal appearsto know its name but is not able to download the boot file, you may
also want to look for an error message on the boot host. Errors from tftpd, bootpd, or inetd
should be recorded by syslog on the host machine. Look in letclsyslog.conf. to determine
where daemon error messagesare being copied to; for example, on our system, /etc/sys-
log.conf contains the line:
*. err; kern. debug; daemon, auth. notice ;mail. crit; user. none /var/adm/mes sages

All daemonerror messageson our system are therefore being copied to Ivarladmlmessages.

7.3.5.2 Updating the arp Table

The arp table on the boot host has a listing of all hostnames, Ethernet addresses,and IP
addresses that the host knows about. You can access this table using the command arp -a:
% arp -a
ncd4.ora.com (140.186.65.14) at 0:0:a7:10:12:bf
rubble.ora.com (140.186.65.11) at 8:0:20:2:fc:90
rock.west.ora.com (140.186.66.10) at 0:0:c:0:63:4a
cca.camb.com (140.186.64.12) at aa:0:4:0:e2:4
harry.ora.com (140.186.65.17) at 8:0:20:7:c4:d4

Keep in mind that if you replace an X terminal with a new one, you may have to manually
delete the cached arp entry with the arp -d command before the new terminal can be recog-
nized:

# arp -d ncd4

If you have an old arp entry or have made a mistake in the /etc/ethers file, you may get the
following error:
duplicate IP address!! sent from ethernet address: ...

7.3.5.3 Name Server Problems

If the X server is running properly but you can't seemto get any clients to open the new dis-
play, there may be a problem in the name server.The name server is primarily responsiblefor
looking up a hostname and returning the IP addressfor that host. You can therefore isolate
the problem to the name server by supplying the IP addressdirectly to the client program. For
example:
lmui@reno % xterm -display 140.186.65.13:0

X Terminals 169
 If this command is successfulbut "hostname: 0" was not, then the problem could be with the
name serverconfiguration, with the NIS configuration, or with the resolver configuration file
(letc/resolv .conf).

7.4 Fonts on X Terminals

Many X terminals have some fonts built into the server, but you usually need to read fonts
from the host machine as well. Most X terminal manufacturers supply a "font tape" with
their product, with fonts that need to be read on your host system. At minimum, the font tape
that comes with the X terminal contains vendor-specific .snf or .pcf versions of the BDF fonts
supplied by the MIT source distribution of XI1. Many vendors also supply some additional
fonts.

We said earlier that for easyset up, just put the fonts in Itftpboot. But for real setup,you prob-
ably want to think a little harder about where to put the fonts and how they should be read.

7.4.1 Font Formats

Every X server vendor supplies its own font tree for that server. Each font tree takes approxi-
mately three to four megabytesof disk space.If you have X terminals manufacturedby three
different vendors, therefore, you're using up 9 to 12 megabytesjust to hold their fonts-not
to mention the fonts for running X on the local display of the host machine.
Luckily, you can often get away without keeping multiple fonts on line. For .snf fonts, there
are four ways that fonts for different servers might deviate: the byte order, the bit order, the
scanline unit padding, and the glyph padding. In most cases,the scanline and glyph padding
for a server is 1 (the default), so you seldom have to consider those variables for incompati-
bilities (although if you find that your charactersare drawing over one another,you're proba-
bly using fonts compiled with a different padding). The byte order and bit order generally go
hand-in-hand. So for most cases, you really need to keep at most only two sets of .snf fonts
on line: one for X terminals that number bytes starting at the high end (big endian), and one
for X terminals that number bytes starting at the low end (little endian).

PCF fonts don't have byte-order incompatibilities, so if all your X terminals support PCF
fonts, you might be able to get away with a single set of fonts.
For example, NCD X terminals are big endian, so if they are reading fonts from a Sun works-
tation (a big endian machine), chancesare that they can read and display the .snf fonts com-
piled for the local server without a hitch. The bdftosnffonl compiler defaults to the byte order
on the host machine, so there should be no problem in font compatibility between Sun and
NCD X servers. In this situation, you would not have to keep the NCD fonts on line, but
could have the X terminals read the Sun-compiled .snf fonts. The easiestway to do this is by
linking the standardXI1 font directory to the server-specificfont directory. For example:
# mkdir /usr/lib/Xll/ncd
# In -B /usr/lib/Xll/fonts /usr/lib/Xll/ncd/fonts

170 X Window System Administrator's Guide

 (You may still want to use the fonts supplied with the X terminal, since they may be more
sophisticatedthan thoseon the core MIT distribution, but that's up to you.)
HDS X terminals are little endian. This meansthat the fonts on a Sun are not compatible with
those supplied by HDS (although fonts on a VAX are).
There is another hitch. Although each of the factors for font compatibility can be overridden
on the bdftosnf command line, the options for a different bit or byte order will apply only to
the glyph section of the font-the header section will still be in the bit and byte order of the
host. So HDS supplies its own font compiler, bdftohds, since they cannot rely on the fonts
compiled by bdftosnf on a big endian machine. Many X terminal manufacturers supply their
own compiler to convert .bdf fonts to their own format.

Some X terminals (e.g., those made by Visual) can read fonts in either byte order. Further-
more, X terminals are beginning to support the .pcf font format, which does not have byte-
order incompatibilities. Tektronix is one vendor that currently sells X terminals supporting
both .pcf and .snf formats.

7.4.2 The Font Server (R5)

With Release 5 of XI1, a lot of the font confusion is cleared up with the font server. R5-com-
patible X terminals (of which there are currently none) supply a field in the setup menu for
the addressof the font server.If your X terminal provides this functionality, and you have an
R5 host available to run a font server, run (do not walk) to Section 5.5 to learn how to enable
the font server on the host. You have been spared a giant headache.

Some X terminal vendors, such as Visual Technology,have their own proprietary font server
mechanism. Although they are unlikely to be compatible with the R5 font server, thesepro-
prietary font servers are worth looking into if running the R5 font server is not an option.

7.4.3 Choosing TFTP or NFS for Font Access

Assuming that your X terminal does not support the font server introduced with XI1R5, you
are stuck with either TFTP or NFS. (Some X terminals also support using FTP, but you're
probably better off not opening that can of worms.)

7.4.3.1 Reading Fonts Using TFTP

It's easy to install fonts to be transferred with TFTP.But since TFTPdoesn't provide any user
authentication, you need to decide whether you want to run it in restricted mode or not, and
either option has its downside.
If you run TFTP in restricted mode, you have to put the font files in the TFTP home directory
tree (usually Itftpboot}. When the X terminal connects to the host using TFTP, it will do a
chroot to Itftpboot and then look for the fonts relative to that directory-so, for example, an
NCD X terminal will effectively look for its fonts in ItftpbootlusrlliblXllined/fonts.

X Terminals 171
 The problem with running TFTP in restricted mode is that it gives you no choice but to install
all your fonts in the TFTP home directory. This may mean somecreative shuffling, just to put
Itftpboot on a disk large enoughto hold all those fonts. Note that the solution that you would
like, which is keeping the fonts in lusrlliblX11 /fonts but creating symbolic links to Itftpboot,
isn't an option-restricted TFTP cannot follow links outside of Itftpboot.
If you run TFTPin unrestricted mode, you can put the NCD font files where you really want
them, in /usr/lib/Xllined/fonts. But you probably don't want to run TFTP in unrestricted
mode-after all, do you want anyone over the Internet to be able to read your /etc/passwd
file?

A possibility is to use NFS to mount the fonts from the samemachine. That is, you might set
up the host ruby to export lusr read-only to itself. On newer NFS implementations, the
I etcI exports would look like:
/usr -ro,access=ruby-

Then have ruby mount /usr/lib/Xl I/vendor/fonts as ItftpbootI usrI lib 1X1II vendor/fonts. In
letclfstab on the samehost:
ruby:/usr/lib/Xll/ncd/fonts /tftpboot/usr/lib/Xll/ncd/fonts nfs ro,bg 0 0

This provides you the convenienceof TFTP without many of the hassles.

7.4.3.2 Reading Fonts Using NFS

If you are using NFS directly to download fonts, check the /etc/exports file on the host to
confirm that the X terminal has permission to read its font directory, and make sure that
directory is exported with the exportfs command. See Section A.5 for more information on
exporting directories under NFS.

Netgroups are particularly useful for grouping several X terminals together that need the
samefonts. See the Nutshell Handbook, Managing NFS and NIS, by Hal Stern (O'Reilly &
Associates, 1991), for more information.

Using NFS to mount the fonts locally on the X terminal can causesomeconfusion. The cryp-
tic error message"X Error of failed request: BadValue" means the font
can't be read becausethe specified path doesn't exist. This may happen becausethe path-
name was mistyped; however, it could also be the result of some NFS confusion-the font
directory may not be properly exported, or it may be mounted on the local machine under
another name. For example, you may mount lexportlusrlliblXlllncdlfonts on a fileserver as
/usr/lib/Xllined/fonts on the local X terminal.The pathname
you specifyto xsetmustreflect
its pathnameon the local machine, i.e., the one running the X server.

Anotherpossiblesourceof confusionis that NFSwill notextendpermissionto anypaththat

is not explicitly exported. That is, if lusrlliblXlllncdlfonts is a symbolic link to
lexportlusrlliblXlllncdlfonts, exporting lusr will not grant accessto the files that are linked
to /export.

172 X Window System Administrator's Guide

 7.5 Configuring for the X Display Manager

If you're using X terminals, you probably want to control them using the X Display Manager
(xdrri). There are other ways of starting sessions,suchas logging on via telnet and starting cli-
ents manually, or using the rexec (remote execution) capabilities supported by some X termi-
nals. But if both the host system and the X server support the XDM Control Protocol (R4 or
later), then you should definitely usexdm.
If you aren't running xdm at all, read Section 3.3 for more information to get it started. See
Section 3.1 for somebackground information on XDMCP.

7.5.1 Configuring the X Terminal for xdm

X terminals generally supply three different ways of running XDMCP:

Direct Calling XDMCP "directly" requires that the name or IP addressof the host run-
ning xdm be supplied. The X terminal will request an xdm login box from that
host and from that host only.

Indirect Calling XDMCP "indirectly" requires that the name or IP addressof the host be
supplied. The host is then expected to passthe XDMCPrequestto another host or
group of hosts. For a host running vanilla XI1R4, an "Indirect" query is treated
the sameas a "Direct" one. For a host running XI1R5, it can be configured to
respond to an "Indirect" query by forwarding the request to another host or by
offering a list of hosts for the user to choose from. See Section 3.5.3 for infor-
mation on how to configure how "Indirect" queries are treated on an R5 host.
Broadcast Calling XDMCP in "broadcast" mode does not require a hostname or address, but
means that the X terminal sends out a general request for an xdm login box
across the subnet. For most X terminals, the first host that responds is the one
that is used. For some smarter X terminals, the X server gathersresponsesfrom
all hosts on the local network and allows the user to choose one to start up on.

If an X terminal doesn't connect to any host running xdm under a Broadcast

query, but can connect to hosts via a Direct or Indirect query, then there is proba-
bly something wrong with the Broadcast addressthat you have configured the X
terminal to use. See your vendor's documentation for information on how to set
the Broadcast address.

Note that Broadcast queries are restricted to the local network or subnet. Unlike
Direct and Indirect queries, you cannot use a Broadcast query to accessa host
through a gateway.

X Terminals 173
7.5.2 Configuring an R5 Host

If the host is using XI1R5, then you need to make sure that the new X terminal is given per-
mission to connect to xdm on the host. The lusrlliblXlllxdmlXaccess file controls which X
serverscan connect to the host. The Xaccessfile also controls how Indirect queries are dealt
with on that host.

For example, to add ncd4 to the list of X serversthat can connect to the host, you can simply
add the line:

ncd4.ora.com

Note that the Xaccessfile acceptswildcards. So ncd4 would already have permission to con-
nect to the host if there were a line such as:

*.ora.com

SeeSection 3.5.3 for more information on how to configure the Xaccessfile.

7.5.3 Configuring an R4 Host

If the host is using XI1R4, you don't need to make any changeson the host for a XDMCP-
compatible X serverto usexdm-you just need to configure the X terminal to useXDMCP.

7.5.4 Configuring xdm Without XDMCP

If either the X server or the host is not XDMCP-compatible(R3 or earlier), then you need to
make an entry in the lusrlliblXlllxdmlXservers file in order to manage the X terminal using
xdm. For example, you can add the line:
ncd4.ora.com: 0 foreign xxx

(The "xxx" is required becausealthough R3 xdm ignores the third field in a foreign entry, the
field cannotbe left empty.)
SeeSection 3.5.2 for more information on how to configure the Xservers file.
The problem with using pre-XDMCPxdm is that, should the X terminal be turned off for any
reason,xdm needsto be restarted before it will know to reconnectto the terminal. If you have
no choice but to use an R3 host system,you might be interested in X terminals that offer their
own proprietary protocol for controlling xdm. X terminals made by Visual, for example, pro-
vide XDSXDM for controlling Release3 xdm for their XDS terminals.

174 X WindowSystem Administrator'sGuide

7.5.5 Setting Up Server Access Control

As described in Chapter 4, there are two current mechanisms for restricting clients from
accessing a particular server: host-based access control and user-based access control.

Host-basedaccesscontrol is controlled entirely by the server. Some X terminals allow you to

keep a list of hosts that you want to allow accessfrom, using the setupmenu on the X termi-
nal. However, it's better to use user-basedaccesscontrol if you can.
User-based access control is controlled both by the server and by the X Display Manager.
Check your X terminal documentationto see if user-basedaccesscontrol is supported.If it is,
then check if xdm is set up to use user-based access control on X terminals. You can deter-
mine this by examining the configuration file for xdm, usually lusrlliblXlllxdmlxdm-config.
The following line:
DisplayManager*authorize: true

specifies that authorization is being used for all X servers managed by xdm on that host.

Host-based access control overrides user-based access control. This can cause complications
when your X terminal supports both types of server access control. Contrary to what your
instincts might be, to enable user-based access control you should make sure that host-based
accesscontrol is also enabled-disabling host-basedaccesscontrol may effectively result in
all hosts having accessto the server, regardlessof any user-basedaccesscontrol in effect. If
you want to use user-based access control exclusively, you should make sure host-based
access control is enabled but the list of hosts that are allowed access is empty. See Section
4.2.4 for more information.

See Chapter 4 for more information on security issues and XI1.

7.6 Remote Configuration of X Terminals

Many X terminals provide a facility called remote configuration. Our experience with
remote configuration has been very positive, so we recommend that if you have more than
one of a single type of terminal, you should consider using remote configuration.
With remote configuration, the parameters in the setup menu can be defined in a file to be
downloaded by the X terminal when it boots. What this does for the administrator is that it
makes it easy to change a given field-the administrator no longer needs to visit each X ter-
minal on the site after hours and change their setup menusmanually, but can simply edit the
remote configuration files for each terminal. The next time the terminal is booted, the new
values will be read.

Another advantage of remote configuration is ease in troubleshooting. The danger of user-

accessiblesetupmenus is that a user might unknowingly change something that disablestheir
terminal. Many terminal manufacturers provide a mechanismfor "locking" the current setup
menu settings with a password-so that only administrators with the password will be able to
make further changesto the X terminal configuration. Using remote configuration, however,

X Terminals 175
 the X terminal is configured at boot time from a file residing on a host. If a terminal's set up
is corrupted, therefore, the user can restoreits settingsjust by rebooting the X terminal.
Another advantageof using remote configuration is that it can help you get out of a jam if for
somereason your current configuration is so corrupted that you cannot even accessthe setup
menu. If you are using remote configuration, you can just edit the file and then reboot the ter-
minal.

Each X terminal vendor has its own syntax for remote configuration. To give you an idea of
what they do, here's a description of how remote configuration is handled by various X ter-
minal vendors.

7.6.1 Remote Configuration on NCD Terminals

On NCD X terminals with remote configuration turned on, each X terminal at boot time looks
for a configuration file whose name is derived from its IP address, in hexadecimal. For
example, an NCD X terminal with IP address140.186.65.13 would look for a configura-
tion file called 8CBA4JOD in the directory lusrlliblXlllncdlconfigs. (See Section A.9 for
information on how to get the hexadecimal equivalent of an IP address.)
If the configuration file for its specific IP addressdoesn't exist, the X terminal then looks for
a configuration file called ncd_std in the samedirectory.
If you are using NFS to read the remote configuration file, the X terminal needsto have read
accessfor the lusrlliblXlllncdlconfigs directory on the host. If you are using restricted TFTP
to read the remote configuration file, the configuration files need to be installed in the
Itftpbootlusr/liblXlllncdlconfigs directory.
The following is a portion of the remote configuration file used by our NCD X terminals:
background = white
backing-store = by-request
baud-1 = 9600
boot-at-reset = yes
boot-server = 140.186.65.25
broadcast-address = 140.186.0.0
data-bits-1 = 8
default-cterm-host =0.0
default-domain = ora.com

virtual-terminal-at-reset = xdm
xdm-access = direct

xdm-server = 140.186.65.25

Now for the goodnews:NCD doesn'trequireyou to write it all in by hand.Instead,you can

setup a singleterminal,makesureit worksto your liking, andthendownloadits parameters
to a file using the Utilities menu.

The next problemis how to tell the terminal to read the remoteconfigurationfile the first
time. There'sa logistical probleminvolved: NCD X terminalssupportNFSonly if they're
usingremoteconfiguration,so if you wantto readtheactualconfigurationfile overNFS,you

176 X WindowSystemAdministrator'sGuide
 need to upload the configuration file initially using TFTP,and then savecurrent valuesbefore
rebooting.

7.6.2 Remote Configuration on Visual Terminals

On Visual X terminals with remote configuration turned on, the X terminal usesa list of host-
namesand optional pathnamesto determine which configuration file to use. This list is sup-
plied in the Remote Configuration Menu. The X terminal will searchfor the configuration
files in the order that they are listed. When a specific pathnameisn't listed for a given host,
the X terminal looks for a configuration file named for its IP address in the
lusrllib/X11/Visual directory on that host. For example, a Visual X terminal with IP address
140.186.65.13 looks for a configuration file called /usr/lib/Xll/Visual/140.186.65.13. If
that file doesn't exist, it then looks for a configuration file called xds-config in the same direc-
tory.

If you are using NFS to read the remote configuration file, the X terminal needs to have read
accessfor whatever directory the configuration files live in. If you are using restricted TFTP
to read the remote configuration file, the files needto be in a subdirectory of /tftpboot, and the
pathnameneedsto be relative to /tftpboot.
Visual X terminals use resourcesyntax for their configuration files. They follow the form:
Visual .model .parameter: value

where model is the particular model of Visual X terminal, such as X19, X19TURBO, X15, etc.
As with standard resource syntax, you can use an asterisk for the model field to have a
resource apply for all models. The following is a portion of a sample configuration file for
Visual X terminals:

! Ethernet Menu
i

Visual*IpNetworkMask: 255.255.255.0
Visual*IpBroadcastAddress: 140.186.0.0

! X Server Features Menu

Visual*DefaultTextFont: 9x15
Visual.XlS.DefaultTextFont: 12x20

Note that we've set things up so that the Visual X15 terminal usesthe 12x20 font for text,
but all other Visual terminals will use the 9x 15 font.

X Terminals 177
7.6.3 Remote Configuration on Tektronix Terminals

For Tektronix X terminals, the syntax for remote configuration files consists of commands
followed directly by parameters. Lines starting with "#" are taken as comments. The remote
configuration file is read using the same file accessmethod that is used for downloading the
server image (i.e., TFTP),so remote configuration is not available for terminals that boot from
ROM.

Tektronix remote configuration files need to be thought of somewhat differently, since the
terminal executeseach line as a command and doesn't just store it as a variable definition.
This meansthat you have to be careful about the sequenceof commands.For example, you
need to declare a host's address using the ip_host_table command before you can use its
hostnamefor thefile Jiost_name_1 command.
The sampleis a portion from a configuration file for Tektronix X terminals:
ip_host_table 140.186.65.25 ruby
ip_host_table 140.186.65.35 opal
file_host_name_l ruby
file_access_l TFTP

7.7 Reconfiguring the Host

When you replace an ASCII terminal with an X terminal, you're giving a user a whole new
world of functionality. You are also allowing that user to use five to ten times the resources
he or she used previously. Whereasa user on an ASCII terminal might run maybe one or two
processesin the background (which usually exit on their own), a user on an X terminal can
go hog wild, running an xclock, xbiff, multiple xterms, a mail reader, a news reader, etc.-all
this before starting actual "work." In addition, xdm forks a copy of itself for every display it
manages.

In this section, we include an example of how to configure a SunOS system to support more
users,processes,pseudo-ttys,and swap space. Refer to your vendor's manual for information
on how to reconfigurethe kernel on your system.

7.7.1 Increasing the Number of Processes

When you set up a site for running multiple X terminals, you probably want to increasethe
number of processesthat the host can handle at once. If the system runs out of processes,it
may give an error:
% Is
No more processes
%

or commandsmay fail silently.

178 X WindowSystemAdministrator'sGuide
 To increase the number of processeson SunOS 4..v, edit the kernel configuration file. The
name of this file follows the form Isyslarchlconflkerneljiame. For our Sun4, this file is
lsys/sun4mlconflRUBY. Edit the maxusers line as appropriate. For example, change:
maxusers 8

to:

maxusers 48

Then rebuild the kernel and reboot:

# /etc/config RUBY
# cd ../RUBY
# make
# cp /vmunix /ovmunix
# cp vmunix /
# sync;reboot

Be careful to follow the guidelines in vendor OS manuals in increasing maxusers. If you

increaseit beyond the specified upper limit, you run the risk of wasting resources.

7.7.2 Increasing the Number of Pseudo-ttys

Another consideration is the number of pseudo-ttys, or ptys, a host can handle. A typical
symptom of running out of ptys is an immediate logout when trying to open a new connec-
tion:

% rlogin rock
Password:
SunOS Release 4.1.2 (ORAWEST) #3: Wed Jul 29 12:50:14 PDT 1992
TERM=(xterm)
Connection closed.

On SunOS, edit the samekernel config file Isyslarchlconflkerneljname. Find the line for pry
devices.

pseudo-device pty # pseudo-tty's, also needed for SunView

The default entry is for 48 ptys,. Appending a number suffix changesit accordingly:
pseudo-device pty128 # pseudo-tty's, also needed for SunView

We have now set up the system to support 128ptys. (See your documentation to learn what
the maximum number of ptys,on your systemis. SunOS4.1.2 can handle up to 256 ptys.)
Next, make more ptys in Idev for each bank of 16 ptys. Since we have expanded to 128ptys,
this would be 128 H- 16 = 8 banks of ptys in total. The pty banks are numbered from 0, so
you'd remake banks 0 through 7:
# cd /dev
# MAKEDEV ptyO ptyl pty2 pty3 pty4 pty5 pty6 pty?
# Is pty?? I we -1
128

Then rebuild the kernel and reboot as shown above.

# /etc/config kernel name

X Terminals 179
 # cd ../kernel name
# make
# cp /vmunix /ovmunix
# cp vmunix /
# sync;reboot

There is often a script in Idev for creating new pseudo-ttys. See your vendor's documenta-
tion for details.

7.7.3 Increasing the Amount of Swap Space

You may need to increasethe amount of swap spacewhen you start to get the dreadederror
message:

Sorry, pid 3924 (eap) was killed due to lack of swap space

There are two ways to deal with swap spaceunder SunOS: either swap to a file or swap to
disk partition.*

7.7.3.1 Swapping to a File

To swapto a file, fist createthe swapfile:

# mkfile -v 64m /work/moreswap
/work/moreswap 67108864 bytes

Then add an entry in I etc If stab as follows:

/work/moreswap swap swap rw 0 0

Finally, enable swapping on the new area:

# swapon -a
Adding /work/moreswap as swap device

7.7.3.2 Swapping to a Disk

To swap to a disk, add an entry in letclfstab to define the new swap partition (in this example,
Idevlsdlb):

/dev/sd2b swap swap rw 0 0

Then, before running swapon, check the current size of the swap space:
# /etc/pstat -T
163/2758 files
829/1223 inodes
74/778 processes
14488/63972 swap

This showsapproximately64 MB of available swap space(with 14 MB alreadyused).

*SeeEssentialSystem
Administration,by AEleenFrisch(O'Reilly & Associates,1991),for moreinformation.

180 X WindowSystemAdministrator'sGuide
 Finally, run swapon and then check the size of the swap spaceagain:
# swapon -a
Adding /dev/sd2b as swap device
# /etc/pstat -T
163/2758 files
829/1223 inodes
74/778 processes
14488/127944 swap

The swap spacehas doubled to approximately 128 MB.

7.8 Related Documentation

Articles on X terminals appearfrequently in periodicals serving the X and UNIX community.

Advertisements (in periodicals that accept them) are also very helpful for keeping track of
the latest and greatest X terminal technology.

In addition, a list of X terminal manufacturers is posted quarterly to the comp.windows.x

newsgroup.

The following Nutshell Handbooks might come in handy: Managing NFS and NIS by Hal
Stern; Essential SystemAdministration by AEleen Frisch; TCP/IP Network Administration by
Craig Hunt; and DNSand BIND by Cricket Liu and Paul Albitz.

X Terminals 181
 8

Building the X Window System

By necessity, you can't do anything with X until it is installed on your system.

This chapter tells you how to build and install X.

In This Chapter:
Installation Issues 185
Should You Use MIT Source? 185
Types of Vendor-supplied X Distributions 186
X from Your OS Vendor 187
X from aThird Party 187
X Source Code from MIT 188
Complete or Client-only Distribution? 189
Installing Multiple X Releases 189
Source Preparation 191
Do You Have Enough Disk Space? 191
Is Your Platform Supported? 192
Applying OS Patches 194
Applying X Patches 194
Creating a LinkTree (Optional) 196
Simplest Case Build 197
Host Problems 198
Disk Space 198
Changing the tmp Directory Using TMPDIR (Ultrix and HP-UX) 199
Changing the tmp Directory Using -temp (SunOS) 200
Shared Library Installation (SunOS) 200
NFS Installation 201
NFS Installation Without Root Access 201
Installation Over the Network (rdist) 203
Installing the termcap or terminfo Definition for xterm 203
Simple Configuration 204
Configuration Parameters 205
 site.def 205
The ProjectRoot Flag 207
The Platform Configuration File (platform.cf) 208
Configuration Example 1 210
Configuration Example 2 211
Configuration Example 3 212
Configuration Example 4 212
Configuration Example 5 213
Other Build Flags 213
xterm Build Flags 214
Building Programs After X Is Installed 214
xmkmf 214
Include Files 215
Libraries 216
More About imake 216
The make Program 216
The C Preprocessor 217
Imake Syntax 219
Comments in imake 219

Multi-line Macros (@@) 220

Concatenating Macros 221
Dealing with Tabs 222
imake Configuration Files 222
A Quick Tour of Files Used by imake 223
Using imake to Build X11 224
Porting Hints 226
Undefined Symbols or Functions 226
Missing Header Files 226
Missing Function Definitions 226
Searchingfor PreprocessorSymbols 228
Related Documentation . .. 230
 8
Building the X Window System

This chapter tells you how to build and install X. If X is already installed, you can skip this
chapter unlessyou want to learn more about what goes on "under the hood."
If X isn't installed on your system,you have two choices: you can build it yourself or you can
purchase pre-built binaries. This chapter begins by telling you what you need to know to
make that decision.

If you decide to build X yourself, this chapter tells you how. The amount of work involved in
building X depends on the type of installation, the platform you use, and the resources that
are available to you (such as disk space,time, tape drive or CD/ROMdrive.) You should ex-
plore each of these factors before you attempt to build X.

8.1 Installation Issues

First you need to decide what you want to install. This section gives a short description of
what types of distributions are available. The easiestinstallations are describedfirst and with-
out much detail. If your configuration falls under one of these categories,then you can bail
out of this chapter early.
If your installation requires more thought (or if you are curious), the remainder of the chapter
provides a guide to completing all but the most complicated installations.

8.1.1 Should You Use MIT Source?

The first thing you need to do is to determine whether you want to build X from the MIT
sources ("vanilla" or "stock" XI1), or whether you'd rather install binaries provided by a
vendor.

Using XI1 binaries supplied by a vendor has the following advantages:

" X supplied by an OS vendor may be easier to use and may be better integrated with appli-
cation software than the "stock" MIT XI1. Some examples of integrated X distributions
would be SGI's IRIX 4.0 environment, SCO Open Desktop and Sun OpenWindows.

Building the X Window System 185

 " Vendors usually provide a stable releaseof X. (MIT releasesgo through many "fixes" be-
fore they settle down, becausethey usually provide new functionality earlier than the
vendor-supplied releases.)

" The vendor may add new functionality to the XI1 distribution; for example, the vendor
may provide support for display PostScript, the Silicon Graphics Graphics Language
(GL), special hardware (such as graphics accelerator cards), and multi-processor operat-
ing systems.

" Some applications may require vendor-specific features that are unavailable in the stock
MIT release of XI1. An example of this would be Sun's AnswerBook documentation
viewer, which runs only under the Sun OpenWindows server.

" You can call technical support (or send e-mail) if you have a question or complaint.
(Whether this leads to a resolution of your problem is another topic altogether.)

" Installation of a vendor-supplied X package is usually a breeze, and often requires little
technical knowledge.

" MIT may not provide a server that supportsall of the vendor's hardware.
Building and configuring the MIT sourceshas the following advantages:
" Support for the "stock" XI1 distribution is pretty good: patches to serious problems are
made publicly available quickly. Anyone with a network connection can pick up a patch
to the MIT sourcevia ftp, or get it via e-mail.

" Vendors are sometimesvery slow to update their X product. You are likely to tire of fight-
ing problems with your vendor release if you know the problem is fixed or never existed
in a newer MIT release. Other X products that you want to use may work only on
releasesnewer than your vendor's. It can be frustrating to be behind in X development
becausethe version of X that came with your system is holding you up.
" You can standardizethe X distribution across severalplatforms by building the MIT ver-
sion for each platform. A common XI1 distribution would greatly simplify a heterogene-
ous network environment.

" The MIT source code is free.

8.1.2 Types of Vendor-supplied X Distributions

Vendor-supplied X can be further divided into two groups:

" X that comes from the vendor of your operating system
" X that comes from third-party suppliers
For both of thesecategories,thedocumentation
that comeswith the packageis your bestre-
source for information on installing their XI1 release.Software installation methods tend to
be very system-specificand may change significantly betweenOS releases.

186 X WindowSystemAdministrator'sGuide
8.1.2.1 X from Your OS Vendor

Some examples of vendor-supplied XI1 are OpenWindows from Sun, DECWindows from
DEC, and AlXWindows from IBM. X from your OS vendor is probably the easiestto install.
In fact, you may not have to install it at all-more and more UNIX platforms are being
shipped with the OS and software packages(such as X) already installed, so you might luck
out and have everything in place when your system is delivered. You should be able to tell if
XI1 is pre-installed by looking in the directory lusr/binlXll or the directory that your vendor
uses (typically lusrlopenwin for OpenWindows, lusr/lpp/Xll for AlXWindows, etc). If the
directory is not empty, you probably have at least some portion of the software already in-
stalled. Some systemshave tools to tell you what software is installed. For example, setld -i
on Ultrix and versions on IRIX. You could also try starting the window system with xinit (or
openwin) to see what happens.

If you need to install an X distribution provided by your OS vendor, the installation proce-
dure for the X package should be similar to that of any other packagethat is bundled with the
operating system.The X package installation should require whatever tool is normally used
for installing software on that platform, i.e., setld for Ultrix, inst for IRIX, cdm or extract^un-
bundled for SunOS, etc.

The vendor may break the XI1 package into separatecomponents: an "execution-only"
package that allows you to run X servers and clients, and a "development" environment for
compiling new X applications. The development environment includes the X libraries,
headerfiles and (make configuration files. (SeeAppendix E for more information on the com-
ponents of the standard X distribution.) If you intend to write your own X programs or com-
pile any of the public domain X applications available on the Internet, you should install a
full development environment. SeeAppendix B for information on installing public domain
software.

Be aware that some vendorscharge extra for the XI1 distribution, and othersinclude it in the
cost of the operating system.You should ask the salespersonabout this before you order your
software configuration.

8.1.2.2 X from a Third Party

There are several third-party vendors who provide pre-compiled XI1 distributions for some
of the more popular platforms. Some vendors are listed in Appendix F and in the comp.win-
dows.x Frequently Asked Questions list.
Third-party X distributions are usually derived from recent MIT releases without adding
much functionality. If you are up to the task of building X from the MIT source, you can
probably duplicate a third-party distribution for your platform and savesome money. How-
ever, it may be easier to purchase a third-party X installation than try to figure out what
patches, bug fixes, and work-arounds are necessaryto build it on your platform. You might
also be able to get invaluable technical support from a third-party vendor.
Furthermore, building the MIT distribution is resource-intensive,consuming large amounts
of disk spaceand CPU time. If theseresourcesare in short supply, this may be reasonenough
to buy a pre-built X distribution.

Building the X Window System 187

8.1.3 X Source Code from MIT

A major part of deciding whether to use the MIT sourceor a pre-built X distribution is how
much work it will be to configure the sources and build X yourself. You might say that the
amount of work required to build X on your platform falls into one of three categories:
" Easy-MIT XI1 for your software and hardware platform is one that is well-tested and
commonplace. Relax and enjoy the experience: you may be able to build and install X by
typing only a few simple commands and get away with not having to understand the
building processat all. (This is pretty amazing considering the size and complexity of the
software.) You may need some minor adjustmentson your system,but they should not be
more difficult than any other tasks you face as a systemadministrator. Platforms on which
your build is likely to be trouble-free are a Sun3 or Sun4 running SunOS4.1.1, a DEC
3100 running Ultrix 4.2, and an RS/6000 running AIX 3.1. Section 8.3 shows an example
of a trouble-free build.

" Some thinking required-You need to find out what magic flags or little fixes are re-
quired to get the MIT source compiled and running on your system. This may require
some detective skills and an understanding of how the building process takes place. A
typical situation that would fall in this category would be building the MIT sourceon an
operating system that is slighter newer or older than the one described in the MIT docu-
mentation. Section 8.5 shows some examples of X builds that may require a little think-
ing.
" Youare on your own-Your platform was bought at a garage sale ... the manufacturer
went out of businessthree years ago and you are the only person who bought one ... or
your platform is so new that you are the only one who has heard of it. Whichever it is,
this chapter addressesonly the most minor of the problems you might encounter. This
chapter will help you compile the libraries and clients, but your big problem is getting an
X server written. Writing an X server on a new machine is quite an undertaking, and is
beyond the scopeof this book.

Which category do you belong in? Well, the degree to which X from MIT source will work
on your system has a lot to do with how popular your platform is. The best way to find out
how much work is involved is to read the release notes, which can usually be found in a file
called RELNOTES.TXT in either the top-most directory of the MIT source or under the mitl
subdirectory.* In the R5 sourcetree, a postscript version is available in RELNOTES.PS, and
troff source(using ms macros) is in a file called RELNOTES.ms.
The releasenotes in the R5 sourcetree list the supportedplatforms under the section entitled
"Building the Release":
3. Building the Release

The core distribution (code under the mit directory) has been
built and tested at MIT on the following systems:
AIX 3.1.5, on IBM RS/6000

* AppendixF providessomeinformationonwhereto find theMIT sources,andSectionA.2 providesinformationon

how to useftp to get a file.

188 X WindowSystemAdministrator'sGuide
 AT&T Unix System V Release 4 V2, on AT&T WGS6386
A/UX 2.0.1
HP-UX 7.0, on HP9000/S300
IRIX 4.0
Mach 2.5 Version 1.13, on OMRON Luna 88k
NEWS-OS 3.3, on Sony NWS-1850
NEWS-OS 5.0U, on Sony NWS-3710
SunOS 4.1.1, on Sun 3, Spare 1, and Spare 2
Ultrix-32 4.2, VAX and RISC
UNICOS 5.1
UTek 4.0
VAX 4.3bsd (with unknown local changes)

If your platform is listed in the release notes, then you're probably in good shape.If not, you
may still be in good shape: the X distribution is frequently ported to new platforms, with the
binary distribution made publicly available. The best way to track the progressof the X dis-
tribution on your platform is to watch the appropriate Usenet newsgroup, or post a query to
either that newsgroupor to comp.windows.x.*
Some examples of useful "ports" that appearoutside of the official MIT distribution are the
XNeXT distribution for NeXT workstations, the X386 server binary for 386-based UNIX
machines,and patchesfor Sun Solaris 2.0.

8.1.4 Complete or Client-only Distribution?

Before buying an X distribution or investing any time in building one from source, you still
have a few more decisions to make.

First, you need to decide whether you want a complete distribution or a client-only distribu-
tion. A complete distribution includes a server, clients, libraries, header files, fonts and confi-
guration files. A client-only distribution could include only the clients and, if necessary,
shared libraries for dynamically linked executables. If you wanted to compile X programs,
you would also need libraries and headerfiles.
Client-only installations make sensefor hosts that don't have a bitmapped console display,
such as a fileserver, compute server, or NFS server. The X clients are expected to display on
remote X servers (for example, X terminals) across a network. Complete distributions make
sense for workstations and for development environments.

8.1.5 Installing Multiple X Releases

Next, you should consider whether you want more than one release of the MIT XI1 installed
at one time. This would come in useful if you intend to test an X application under more than
one X release.

* comp.windowsjc also has an e-mail addressfor those who cannot get news, [email protected].

Building the X Window System 189

For example, you might want to have Sun OpenWindows, MIT R4, and MIT R5 distributions
residing on your platform at the same time: you could do this so you can test clients under
each environment. Each distribution can have its own directory hierarchy.
As a example of this, OpenWindows could be installed under /usr/openwin, MIT X11R4
under lusrlXUR4, and MIT XI1R5 under /mrlXHR5:

Contents OpenWindows X11R4 X11R5

Binaries /usr/openwin/bin lmrlXllR4lbin lusrlXHR5lbin
Libraries /usr/openwin/lib /usr/XHR4llib lusrIXllRSIlib
Headers /usr/openwin/include lusr/XllR4lindudelXll lusrlXURSIincludelXll

Another possibility is that you can run a server from one MIT releasewith the client distribu-
tion from another. You might do this if you are installing a new version of X that doesn't sup-
ply a server for your workstation console: you can continue to use the vendor supplied server
with updated clients until an updated serveris available for your display hardware.
Mixing clients with a server from a different release may have unexpected results. For ex-
ample, newer X servers have the SHAPEextension, which allows windows to be shapesother
than rectangular. If you run the oclock client under a server without this extension, it would
appearas a squareinsteadof a circle, as shown in Figure 8-1.

r
Figure 8-1. oclock without the SHAPE extension

With the SHAPEextension, oclock appearsas it should, as shown in Figure 8-2.

Figure 8-2. oclock with the SHAPE extension

190 X WindowSystemAdministrator'sGuide
 8.2 Source Preparation

You can obtain the sourcecode to X from any of the sites listed in Appendix F. The directory
structure may vary slightly, but at the top of the source directory should be the mitl and con-
tribl directories. The contents of the mitl directory are usually referred to as the core distri-
bution. The core software is supported by MIT and is usually included in every X distribu-
tion. The contribl area is composed of "contributed" software that is not directly supported
by MIT. If you have a problem with contrib software, you would typically complain directly
to the author of the specific package,instead of to the X Consortium.
Over time, programs are promoted from contrib to core status if they gain MIT support, or
demoted from core to contrib if they become obsolete(as uwm was). It is unusual to compile
the entire contrib distribution; the typical practice is to compile and install the entire core
distribution and then selectively compile just the sections you want from contrib. If you are
using a common platform, you will likely be able to survive with only the core software.

When you have obtained the source, there are a few things to do before you can install X:
" Figure out if you have enough disk space.

" Figure out to what extent your platform is supported.

" Make sure your platform is up to date with OS patches.

" Apply all the patchesto the X distribution.

" Create a link tree (optional).

8.2.1 Do You Have Enough Disk Space?

One of the first problems that many run into is the amount of disk spaceconsumed by the
source code. On top of that, additional disk spaceis neededto compile and install the source
code.

Description Size (in Mbytes)

R5 core source 79
R5 contrib source 135
Building R5 core approx. 50-120
Building R5 contrib 300+
Installing R5 core 25-60
Installing R5 contrib 150+

The amount of space required for compiling the core distribution varies considerably from
operating system to operating system.The type of processor (e.g., CISC or RISC),debugging
options and shared libraries will all affect the size of the installation. Read Section 8.4.1 for
some ideas on how to reduce the amount of disk spacerequired for compilation and installa-
tion.

Building the X Window System 191

8.2.2 Is Your Platform Supported?

Before you go anywhere, find out if your platform is one of those supported by the XI1 re-
lease that you want to build. As suggestedin Section 8.1.3, look at the RELNOTES.TXT file in
the mill directory. If your operating system and platform are listed, you are very likely to be
able to produce a working version with very little work. The supportedplatforms are listed in
the section entitled "3. Building the Release":

The core distribution (code under the mit directory) has been built and
tested at MIT on the following systems:

AIX 3.1.5, on IBM RS/6000

AT&T Unix System V Release 4 V2, on AT&T W3S6386
A/UX 2.0.1
HP-UX 7.0, on HP9000/S300
IRIX 4.0

If you are unsure of what type of platform and operating system you are running, use one of
the following methods to figure it out:
" Check the packaging of the OS distribution software for releaseand version information.

" The uname command is available on most systems.For example:

% uname -a
SunOS ruby 4.1 2 sun4

This indicates that the host ruby is a Sun4 running SunOS4.1.

% uname -a
A/UX quartz 2.0.1 SVR2 mc68030

The host quartz is a Macintosh running AUX 2.0.1.

% uname -a
IRIX pebble 4.0.1 11150233 IP6

The hostpebble is a Silicon Graphics running IRIX 4.0.1.

" The letclmotd file is sometimeshelpful:
% cat /etc/motd
SunOS Release 4.1.2 (RUBY) #1: Fri May 29 10:55:44 EOT 1992

You may also extract the OS name from the kernel using the strings command:
% strings /vmunix I grep SunOS
SunOS Release 4.1.2 (RUBY) #1: Fri May 29 10:55:44 EOT 1992

" The arch or mach commandsare available on some systemsto tell you the architecture of
the host:

% mach
spare
% arch
sun4

" Ask someone who knows.

192 X WindowSystemAdministrator'sGuide
The next question is, does an X server exist for your display hardware? Check the release
notes for the supporteddisplays on your platform. The section entitled "Structure of the MIT
sources" contains a list of supportedservers:

DECstation 2100/3100 monochrcme and color displays DECstation 5000 CX

and MX displays IBM RS/6000 skyway adapter Macintosh monochrome and
color displays MIPS monochrome and color displays

You need to find out what sort of display hardware you have, and then find out whether it is
supportedfor your platform. If you don't know what type of display is installed on your sys-
tem, some operating systemsprovide a command that might help. For example, SunOShas
the dmesgcommand, which reports system diagnostics. Among thesediagnostics is a line re-
porting what sort of display hardware was installed at boot time.
% /etc/dmesg

cgthreeO at SBus slot 2 0x0 pri 7

cgthreeOis a color frame buffer. As the boot messagesmay get lost with time, you could also
reboot the system and watch it during the auto-config phase where it looks for each attached
device.

The manual pages for the X server should contain descriptions of supported graphics hard-
ware.* They are located in subdirectories of the server source code. A quick way to find
them is:

% find mit/server -name '*.man' -print

mit/server/ddx/macII/XmacII.man
mit/server/ddx/sun/constype.man
mit/server/ddx/sun/Xsun.man
mit/server/ddx/sun/kbd_mode.man
mit/server/ddx/dec/qvss/Xqvss.man
mit/server/ddx/dec/qdss/Xqdss.man
mit/server/ddx/dec/ws/Xdec.man
mit/server/ddx/mips/Xmips.man
mit/server/ddx/x386/X386.man

The manual page iorXsun lists the cgthree as a supporteddisplay:

/dev/cgthreeO
This color display is available on both the Sun386i
and SPARCstation 1 platforms.

You may also find some information in README files in the server sourcedirectory:
% find mit/server -name README -print
mi t/server/ddx/itm/REAEME
mit/server/ddx/macII/REAEME
mi t/server/ddx/sun/REAEME
mit/server/ddx/omron/REAEME

* If you have the MIT documentation, hardcopy of the server manpages are included in it. They are also in present in
the document millhardcopy /man/'man.PS.Z.

Building the X Window System 193

 ndt/server/ddx/cfb/REAEME
mit/server/ddx/x386/REAEME
mit/server/ddx/x386/cfb.banked/REAEME

The cgthree is mentioned in mitlserver/ddxlsunlREADME:

Sun/2 bw2 cg2/3/5

Sun/3 bw2 cg2/3/4/5
SPARCstation cg3/6

From this information, you can determine that the Sun server supports the cgthree frame buf-
fer that you have installed on your system.

If your platform is supported and a server exists for your display hardware,then you're home
free.

8.2.3 Applying OS Patches

You should make sure your OS has the latest patches,as the MIT X distribution may rely on a
patch being in place in order for it to work properly. This is especially true for security and
compiler patches, as X relies on setuid programs and also tends to expose weaknessesin
compilers during the build process.
The mechanism for obtaining OS patches varies depending on the vendor, but it usually in-
volves a support contract or calling for technical support. Some vendors make their OS
patches available on the Internet or from mail servers.

8.2.4 Applying X Patches

Before continuing with the build, you should verify that you're using the latest version of the
MIT source and have all official MIT "fixes," or patches,applied. Some patches may affect
installation or close security holes, so it's always a good idea to install the latest patch.
If you obtained the sources from a reputable location and they appear to be unmodified, try
looking at the file mitlbug-report. There should be a line resembling:
R5, patch-level-0

"patch-level-0" indicates that no official patcheshave yet beenapplied. The patch-level num-
ber is incrementedas each patch (or "fix") is applied.
You should go back to wherever you obtained the MIT source for the available patches.If
you got the sourcefrom export.lcs.mit.edu,the patchesare in the lpublR5lfix.esdirectory. The
contents of this directory are:
fix-01 fix-05 f.ix-09 fix-13 sunGX.uu
fix-02 fix-06 fix-10 fix-14
fix-03 fix-07 fix-11 fix-15
fix-04 fix-08 fix-12 fix-16

194 X WindowSystem Administrator'sGuide

There are 16 patchesavailable for R5 at the time of this writing.*

The fixes are small enough to be sent through mail and are available through a mail archive
server. SeeSection A.3 for information on getting a patch through the mail.
Patchesare applied using the patch program. If patch isn't already installed on your system,
the sourcefor this program is available in the mitlutillpatch directory.
The top of each patch file describeshow to use the patch program to install the patch, for ex-
ample:
Release 5 Public Patch #1
MIT X Consortium

This patch comes in two parts: this file, and the file "sunGX.uu".
(If you obtained this patch via the xstuff mail daemon, and you
do not have "sunGX.uu", get it with the request "send fixes
sunGX.uu".)

To apply this patch:

cd to the top of the source tree (to the directory containing the
"mit" and "contrib" subdirectories) and do:
patch -p -s < ThisFile
Patch will work silently unless an error occurs. You will likely
get two warning messages, which can be ignored:
mkdir: mit: File exists
mkdir: mit/hardcopy: File exists
If you want to watch patch do its thing, leave out the "-s"
argument to patch.

Next, from the same top-level directory do:

uudecode sunGX.uu
rm -f mit/server/ddx/sun/sunGX.o.dist
uncompress mit/server/ddx/sun/sunGX.o.dist

This example assumesyou created a directory for patches called fixes in the mit/ directory.
Apply the first patch (fix-01) simply by following directions:
% Is mit/fixes
fix-01 fix-05 fix-09 fix-13 sunGX.uu
fix-02 fix-06 fix-10 fix-14
fix-03 fix-07 fix-11 fix-15
fix-04 fix-08 fix-12 fix-16
% patch -p -s < mit/fixes/fix-01
mkdir: mit: File exists
mkdir: mit/hardcopy: File exists
% uudecode mit/fixes/sunGX.uu
% rm -f mit/server/ddx/sun/sunGX.o.dist
% uncompress mit/server/ddx/sun/sunGX.o.dist

(As mentioned in the instructions, the mkdir errors can be ignored.)

*The sunGX.uu file is a replacement object file for the Sun GX graphics accelerator. The .uu extension indicates that
it is a binary file that has been converted to ASCII text by the uuencode program. This makes it possible to send a bi-
nary file throughthemail. Whenthe sunGX.uufile hasbeencopiedto your system,run the uudecode
programon it
to recreate the binary file.

Building the X WindowSystem 195

 Make sure you follow the directions and pay careful attention to the ordering of the patches.
When you have exhausted all the available patches,the "patch-level" number will be incre-
mented to the number of the last patch.

If you get an error messagesuch as:

reversed (or previously applied) patch detected! Assume -R? [y]

then abort the patch program, as it is likely that you are applying the patches in the wrong or-
der or are applying the samepatch twice.
Patchesto contrib software are applied in a fashion similar to the core patches,but they are
organized by specific packages.If you obtain them from the host export.lcs.mit.edu,they are
in the directory IpublRSIcontrib-fixes.

8.2.5 Creating a Link Tree (Optional)

One method of managing the X source distribution is to create a "link tree" of the MIT
source code. The directory structure is the sameas the original MIT distribution, but the files
in the directories are symbolic links back to the original files. If the X distribution is built
within the link tree, the object files and libraries will reside in the copy, not in the original.
Using link trees makes it possible to build any number of different sets of binaries from one
set of sourcecode files. This makes it very easy to maintain a group of binaries for different
platforms. It also conservesdisk space, as the symbolic links will take up less spacethan a
copy of the source files. If you are going to build the distribution only once, however, you
may not want to use a link tree, since it complicates the directory structure and usesup disk
space when creating links.

Link trees may be the only way to effectively use read-only copies of the X source, such as
those mounted from a CD/ROM.

For example, the source area could look like:

% Is -F
mit/ rs_aix31/ sun3_411/
pmax_ul42/ sgi_40/ sun4_411/

The rs_aix31, sun3_411,pmax_ul42, sgi_40, and sun4_411 directories* are link trees that are
linked back to the mit directory. MIT supplies a shell script called Indir that createsthe tree
for you. You can find Indir in the sourcedistribution as mit/util/scripts/Indir.sh.

*The exampledirectorynamesare borrowedfrom AFS.Theyareintendedto describea platformandtheversionof

the operating system. For example, sun4_411 indicates a Sun4 running SunOS 4.1.1.

196 X WindowSystemAdministrator'sGuide
 To build a link tree:

1. Install the Indir program:

# cp mit/util/scripts/lndir.sh /usr/local/bin/lndir
# rehash

2. Create a directory for the tree to reside in:

# mkdir sun4_411

3. cd into the new directory:

# cd sun4_411

4. Run the Indir program, supplying the relative path of the original source tree:
# Indir ../mit
config:
extensions:
include:
PEX:
lib:
xinput:

When Indir finishes, you will be left with a usablecopy of the X source tree.

8.3 Simplest Case Build

If you have confirmed that you have adequate disk space, have applied all the available
patches, and are working on a supported platform, then you may be able to install the X core
software quickly and painlessly.
This example usesthe Sun4 running SunOS4.1.1, as it is one of the most trouble-free builds.
If you want to build X using all default settings, change directories to the top of the distribu-
tion (usually mit/) and type:
% make World >& world.log

If you would like to monitor the progressof the build, use the tail program on the log file:
% tail -f world.log

The build will probably take several hours on even the fastest machines.
When the make is complete, check for errors; any build problems should be reported in the
file world.log.* Examine the file for the messages"not made becauseof or "Error." You can
the grep program to searchfor the ":", as it is commonly present in error messages:
% grep ":" world.log
Sun Jun 7 23:12:09 PDT 1992

*Be careful to search the entire file for errors, as it may still have the message"Full build of Release5 of the X Win-
dow System complete." at the end even if there were problems with the build. This is becausethe make World target
invokes make with the -k option, telling it to ignore non-fatal errors.

Building the X Window System 197

 make: Fatal error: Command failed for target "subdirMakeflies'
make: Fatal error: Command failed for target "Makefiles'
make: Fatal error: Command failed for target "World'
make: Fatal error: Command failed for target "World'

If there are no errors, the next step is to install the distribution. In this example, we use the
default installation pathnames-see Section 8.5.1.2 for information on how to changethe de-
fault pathnames.

If you want to install X as an unprivileged user, you will need write permission to lusr/lib,
lusr/bin, I usrI include, /usr/man/man3, and lusr/manlmann. It is probably easier to install X
as root, instead of touching up permissions after the installation is completed. (The permis-
sions for the installed files are very important to the security of the X distribution.)
Become the superuser:
% su
Password:

Install the distribution:*

# make install >& install.log

Install the manual pages (if desired):

# make install.man >& man.log

If there are no errors at this point, X should be installed and usable. Any remaining adminis-
tration work would involve customizing the installed files for your site. For example, you
may want to configure the X Display Manager. If so, seeChapter 3 for more information.

8.4 Host Problems

There are some problems that can disturb even the default X build. These problems have
more to do with the host configuration than with the X installation itself; that is, problems
with disk space, shared libraries, or NFS.

8.4.1 Disk Space

There are several stagesin the build processthat can consumelarge amounts of disk space.
Optimization options
The -O flag to the C compiler turns on optimization and can generate very large
temporary files. Thesefiles are usually written to Itmp.

*Note thattheinstall processwill writeto the sourceareain somecases.Oneexampleof this occurswheninstalling

thextermbinaryfor the Sunplatform,as the binaryis re-linkedto overcomea securityproblemwith Sunsharedli-
braries.

198 X WindowSystemAdministrator'sGuide
 Debugging options
The -g flag to the compiler tells it to include information in the object files to be
used by a debugger. This can increase the size of the executable to five or more
times the size of an object compiled without the -g flag, depending on the com-
piler used.
Library creation
The ar command builds libraries and may generate large temporary files, usually
written to limp. The HasLargeTmp configuration flag controls the location of
the temporary file when the library for PEX (the PHIGSExtension to X) is creat-
ed. If HasLargeTmp is set to YES, the Itmp directory is used; if set to NO, ar
will use the current directory to store the temporary file. You can also choose
not to build the PEX library by setting the BuildPex flag to NO-see Section
8.5.1 on build flags).

Since most of the temporary files are stored in the Itmp directory, you need to have anywhere
from 10 to 20 megabytesfree in Itmp. If this is not possible, most compilers and archivers al-
low alternate directories to be specified. To find out how to redefine which directory to use
for temporary files on your system, see the manual pages for the C preprocessor (usually
named cpp), the C compiler (usually cc), the ranlib command,and the ar command.*

8.4.1.1 Changing the tmp Directory Using TMPDIR (Ultrix and HP-UX)

On some systems,the ar command checks if the environment variable TMPDIR is set. If so, ar
uses the specified directory as an alternate location for temporary files. You might set
TMPDIR if you ran out of disk space.For example, if the make producesthe following errors:
ar rul libphigs.a archive/ar*.o c_binding/cb*.o cp/cp*.o cp/psl.o
ess/
css*.o error/
er*.o input/sin*.o pex/pex*.o util/ut*.o ws/ws*.o ws_type/wstx*.o
ranlib libphigs.a
/usr/bin/ranlib: 13832 Memory fault - core dumped*** Error code 139
*** Error code 1
Stop.
*** Error code 1
Stop.
*** Error code 1
Stop.

The ranlib program has run out of disk spaceand has died. You can setTMPDIR and start the
build processagain:
% setenv TMPDIR .

This tells ar to createtemporary files in the directory from which the ar command is invoked,
instead of ml tmp.

*On some systems, the ranlib command will be just a shell script that calls ar or it will not be present at all. This
would be true for systems such as the SGI Iris, DecStation, and MIPS machines which use the MIPS compiler suite.

Buildingthe X WindowSystem 199

8.4.1.2 Changing the tmp Directory Using -temp (SunOS)

On somesystems,the C compiler acceptsthe -temp= flag to specify an alternatedirectory for

temporary compiler files. The optimizing pass of the compiler will sometimes create large
files, causing an error such as:
compiler(iropt) error: write_irfile: No space left on device
*** Error code 1
Stop.
*** Error code 1
Stop.
*** Error code 1
Stop.

Call cc with the -temp= flag to redefine where temporary files are placed:
% cc -O -temp=/mondo -c foo.c

If you want this flag to be used when building the entire X distribution, it will have to be ad-
ded to the platform configuration file (e.g., sun.cf) for it to show up in every Makefile. See
Section 8.5.2 for an example of configuring your platform configuration file to use the
-temp- flag.

8.4.2 Shared Library Installation (SunOS)

Under SunOS, the location of shared libraries is stored in a cache file called I etc/Id. so.cache.
The cache file needs to be rebuilt whenever a shared library is added to the system. The X
distribution adds several shared libraries, and most clients cannot run until the cache is up-
dated.Clients will report an error messagesuch as:
Id.so: lihXll.so.5: not found

Running the Idconfig command (as root) should fix this:

# Idconfig

(Rebooting the system would also work, since Idconfig is run from letclrc.local at boot time.)
If the X binaries are intended to be NFS-mountedand executedon diskless workstations, you
need to repeat the process on each of the remote machines. Since each host has its own pri-
vate letclld.so.cache file, the Idconfig command has to be run on each of the disklessworksta-
tions. To simplify this process, you can use the rdist program, or even use a simple shell
script. The following is an example using the C shell:
# foreach I (hostl host2 host3 host4)
? rsh $1 Idconfig
? end

(This example depends on each of the remote workstations having the fileserver listed in
l.rhosts)

200 X Window System Administrator's Guide

 8.4.3 NFS Installation

You may chooseto install X on a filesystem that is NFS-mounted from another host. You'll
have problems installing X if the NFS-mounted filesystem does not allow root accessover
the NFS link. For security reasons,it's a bad idea to allow remote root usersto write to your
filesystem, but you can add root accesstemporarily to allow you to build X.
For root to be able to write to an NFS-mounted partition, you needan entry for the local sys-
tem in the /etc/exports file on the remote system.* For example, to give temporary root per-
mission for the lusr directory to the host named rock, you could change the following line in
/etc/exports:
/usr -access=rock

to:

/usr -root=rock, access=rock

On systemswith the newer version of NFS, run the exportfs command to make this take ef-
fect:

rubble# exportfs -v /usr

re-exported /usr

Back on the local host, the installation can proceed from this point as if it was taking place on
a local filesystem. Build X on rock:
% make world >& world.log

When the installation is complete, the entry in /etc/exports should be changed back to what it
was and then re-exported with the exportfs command:
rubble# exportfs -v /usr
re-exported /usr

8.4.3.1 NFS Installation Without Root Access

An alternative to giving temporary NFS root accessto the remote directory is to install the
distribution as an unprivileged user and change the ownership of the files later. The problem
with this approach is that it opens the system to attack during the installation, so it should be
avoided if possible.

For this example, the ownership of the target directories is changedjust long enough for the
installation to take place. The permissions are then touched up as root. As in the previous
example, the host that has the compiled X source on it is named rock and the host that NFS-
mounts the rock partition is named rubble.

*If you have an older version of NFS, the /etc/exports entries are simply the filesystem names followed by the hosts
which have access. Changesto the file will have an immediate effect. This is in contrast to the current system,which
uses the exportfs command to notify the system of changes in the /etc/exports file and supplies different levels of per-

Building the X Window System 201

1. Become the superuseron rubble:
rubble% su
Password:

2. Create any directories you need that do not exist:

rubble* mkdir /usr/bin/Xll /usr/lib/Xll /usr/include/Xll

3. Change ownership of the top level installation directories to your user ID (cap, in this ex-
ample). Note that someonebreaking into your account would also be able modify the sys-
tem areas while they are writable by you.
rubble* chown eap /usr/bin/Xll /usr/lib/Xll /usr/include/Xll \
/usr/lib /usr/man/man3 /usr/man/mann

4. Now complete the installation under your own account on rock. Install the distribution
from the NFS-mountedpartition:
rock% make install >& install.log

Install the manpagesif you want them:

rock% make install.man >& man.log

5. Back on rubble, change the ownership back to root and group wheel:*
rubble* chown -R root.wheel /usr/bin/Xll /usr/lib/Xll \
/usr/include/Xll /usr/man/man3 /usr/man/mann

The -R flag recursively chowns all files in subdirectories. If the chown commandon your
systemdoes not support the -R option, you could use the find command instead:
rubble* find /usr/bin/Xll /usr/lib/Xll -exec chown root.wheel {} \;
rubble* find /usr/include/Xll -exec chown root.wheel {} \;
rubble* find /usr/man/man3 /usr/man/mann -exec chown root.wheel {} \,

6. Change ownership for only the top-level directory of /usr/lib, as this maintains ownership
information on the many non-Xl 1 files within this directory:
rubble* chown root /usr/lib

7. Now fix permissionsfor the xterm and xload clients.

rubble* chmod 4755 /usr/bin/Xll/xterm
rubble* chgrp kmem /usr/bin/Xll/xload
rubble* chmod 2755 /usr/bin/Xll/xload

(xterm needs to be installed setuid root, xload needs to be setgid group kmem, as
/dev/kmemis readableonly by the kmem group.)

' If your versionof chowndoesnot supportthe user.groupsyntax,usechownfor theuserandchgrpfor thegroup.

202 X WindowSystem Administrator'sGuide

 Under SunOS, you will also need to rebuild the sharedlibrary cache, as describedin Section
8.4.2:

rubble# Idconfig

8.4.3.2 Installation Over the Network (rdist)

A software distribution mechanismsuch as rdist may also be used to install X, but it will re-
quire at least one complete installation to be in place before it can be distributed to other
hosts. To use rdist, a "master" copy is created on one host, and then rdist is used to duplicate
it on other hosts.

rdist commandscan be supplied on the command line or in a command file called a Distfile.
A sampleDistfile might look like this:
HOSTS = ( nobble )
FILES = ( /usr/lib/lib*X* /usr/lib/libphigs.a /usr/bin/Xll
/usr/lib/Xll /usr/include/Xll /usr/man/mann /usr/man/man3)

${FILES} -> ${HOSTS}

install ;
notify root@rubble ;

This Distfile copies an X distribution over to a host named rubble. The notify keyword sends
mail describing what files have been installed. This is handy if you run the command regular-
ly to keep the X distribution updated.
The Distfile can executed with the following command line:
source! rdist -f Distfile
updating rubble

For a network of Sun workstations, you can also use the special command within the Distfile
to run the Idconfig command on the remote host whenever a new shared library is copied
over:

special /usr/lib/lib*X*.so.* /usr/etc/ldconfig ;

Seethe manual pagefor rdist for more information.

8.4.4 Installing the termcap or terminfo Definition for xterm

The xterm program works best with the xterm terminal definition supplied in the mit/cli-
ents/xterm directory. If xterm does not work properly, or is missing altogether, you may need
to install the terminal definition. For example, the following is an error caused by a missing
description for xterm when you log in and your .login script tries to set the terminal type us-
ing tset:
% telnet crufty
Trying 140.186.64.3 ...
Connected to crufty.ora.com.
Escape character is '"]'.

login: eap

Building the X Window System 203

 Password:

TERM= (xterm)
Type xterm unknown
TERM= (unknown)

You might also get error messageswhen you try using your favorite editor:
% vi foo
xterm: Unknown terminal type
I don't know what kind of terminal you are on - all I have is 'xterm'.
[Using open mode]
"foo" [Read only] 3564 lines, 133099 characters

:q!
% emacs foo
emacs: Terminal type xterm is not defined.

You could use vtl02 as a temporary value until you are able to install the xterm entry.
% setenv TERM vt!02

The terminal definition for systemsusing termcap can be installed simply by inserting the
contentsof the file called mitlclients!xterm/termcap into the letcltermcap file on your system.
It's a good idea to insert the termcap definition before any other definitions, since xterm is
likely to be used frequently.

The terminfo definition can be installed by using the terminfo compiler, tic. For example:
# tic mit/clients/xterm/terminfo

(Note that you must be root for this to succeed.)

The terminfo definition is placed in lusrlliblterminfo/xlxterm.
Seethe Nutshell Handbook termcap and terminfo (O'Reilly & Associates, 1991)for more in-
formation on the termcap and terminfo terminal databases.

8.5 Simple Configuration

If you are not satisfied with the default configuration, you can change somesimple configura-
tion parameters,as described in this section. These parametersneed to be configured before
the build is begun.

The files used to configure the X compilation and installation reside in the directory mitl con-
fig. The syntax within these files should look familiar if you have used the C preprocessor
(cpp) before. If you are not familiar with C preprocessorsyntax, you should still be able to do
the right thing by looking at other examples within the configuration files. Section 8.7 gives
some more background on intake syntax; for most configurations, you can probably figure it
out on your own.

You need to modify two files that will affect the build process:site.def, which definesparam-
eters for your particular site, and a platform-specific file (e.g., sun.cf) which defines parame-
ters for your particular platform.

204 X Window System Administrator's Guide

 A list of systemsand their corresponding .cf files can be found in the mitlRELNOTES.TXT file,
under the section "3.2.1 The vendor.cf file." Find the appropriate platform.cf file from this
table:

AIX itm.cf
ADS itm.cf
AT&T Unix SVR4.2 att.cf
A/UX macll.cf
BSD bsd.cf
ConvexOS convex.cf
DG/UX DGUX.cf

Before you modify any of these files, make a backup copy. (You should probably choose
someextension other than .bak or .orig, as theseextensionshave special significance to other
programs.)
% cd mit/config
% cp sun.cf sun.cf.keep
% cp site.def site.def.keep

You could also use a revision control system,such as RCS or SCCS.

You may also have to give yourself write permission to the files:
% chmod u+w sun.cf site.def

8.5.1 Configuration Parameters

There are many configuration parametersthat you can modify. Only a subsetof those avail-
able are described here, as there are many special-purpose flags. The complete list is in
mit/config/README.

8.5.1.1 site.def

The site.def file defines configuration parametersto be used for your entire site. Your site
may include more than one type of platform or operating system;the site.def file is consulted
regardlessof the platform type, whereasthe platform.cf file is looked at only when building
on a particular platform.
An unmodified site.def looks like this:
#ifdef BeforeVendorCF

/* ttdefine HasGcc YES */

#endif /* BeforeVendorCF */

#ifdef AfterVendorCF

/*
#ifdef ProjectRoot
#undef ProjectRoot
#endif

Building the X WindowSystem 205

 #define ProjectRoot /usr/XllR5
*/

#en«±Lf /* AfterVendorCF */

There are two sectionsto the site.def file. The first is delimited by the BeforeVendorCF con-
ditional and the secondby AfterVendorCF. As you might guess,the first section contains any
flags that should be set before the platform.cf file is read, and the second section has flags
that should be set afterwards.

(Note that the section containing the ProjectRoot flag is commented out with the /* and
*/ characters. The ProjectRoot flag is discussedin Section 8.5.1.2.)
A modified site.def might look something like this:
#ifdef BeforeVendorCF

/* #define HasGcc YES */

#endif /* BeforeVendorCF */

#ifdef AfterVendorCF

/*
ttifdef ProjectRoot
frundef ProjectRoot
#endif
#define ProjectRoot /usr/XHR5
*/
#define InstallXdmConfig YES
#define InstallXinitConfig YES
#define InstallFSConfig YES
ttdefine StripInstalledPrograms YES
#define HasXdmAuth YES
ttdefine ExpandManNames YES

ttendif /* AfterVendorCF */

(You should consult the version of configlREADME that comes with your release,as many of
the flags are release-specific.)
You might want to modify one or more of the following flags:
InstallXdmConfig
By default, the configuration files for the xdm program are not installed. By set-
ting InstallXdmConfig to YES, the xdm configuration files are installed in
lusrlliblXlllxdml.

Warning: If you have files in lusr/liblXlllxdml that you have already config-
ured, copy them to a safeplace before starting the installation. Enabling this flag
will overwrite files that you may have customized.
InstallXinitConfig
By default, the configuration files for the xinit program are not installed. By set-
ting InstallXinitConfig to YES, they will be copied to lusrlliblXlllxinitl.
Thesefiles are used by the startx front end to xinit.

(The samewarning for InstallXdmConfig applies here as well.)

206 X Window System Administrator's Guide

 InstallFSConfig
The font server configuration files are not installed unlessthis flag is set to YES.
StripInstalledPrograms
Setting this flag to YES will strip binaries as they are installed. The usual reason
for doing this is to save disk space: removing the symbol table from the binary
will reduce its size. It will be difficult to debug any run-time problem if the pro-
grams are stripped, but this is not a concern to most X users.
HasXdmAuth

This flag indicates that the XDMCP library should include DES code. DES, or
Data Encryption Standard, is an encryption scheme used in the authorization
process. There are restrictions on exporting DES outside the United States. This
flag must be on if you want to use the XDM-AUTHORIZATION-1method of
server access control. See Section 4.3 for more information.

ExpandManName s
Some operating systemshave restrictions on filename length. To deal with this
problem, the manual pages for X library functions have their names shortened to
14 characters. If your operating system does not have this problem, the manual
page filename can be expanded to its full name (for example, XTranWCo.3is ex-
pandedto XTranslateCoordinates.3}.
HasLargeTmp
This flag indicates that you have enough disk spacein Itmp for the ar command
to create its temporary file. Setting this parameterto NO instructs ar to use the
current directory.

InstallLibManPages"
There are two sectionsof manpages:client manpagesand library function man-
pages. If this flag is set to NO, it prevents the library manual pages from being
installed with the make install.man command. This flag is set to YES by default.
You might set it to NO if no one at your site intends to program in X and if disk
spaceis low. (The library manpagesconsumeapproximately 2 megabytesof disk
space.)

8.5.1.2 The ProjectRoot Flag

The ProjectRoot flag defines the "root" directory for the build. It is not used in the ex-
ample site.def file, but can be easily enabled by removing the C comments surrounding this
section:

ttifdef ProjectRoot
#undef ProjectRoot
#endif
ttdefine ProjectRoot /usr/XHR5

If ProjectRoot is already defined, it is first undefined. (The reason for this test is that
some of the platform.cf files define ProjectRoot by default. The C preprocessor will
complain if a flag is defined twice.)

Building the X WindowSystem 207

 The typical use of this flag is to install X in a non-standardlocation. You might do this for
one of the following reasons:
" You may need to have more than one release installed at one time. You could have
XI1R3 under lusrlXHR3, XI1R4 under lusr/XHR4, and XI1R5 under lusrlXHR5. This
may be useful for migrating an application from one releaseto another.As it is much eas-
ier to install R5 in "non-standard" location than previous releases,you may wish keep a
pre-R5 releasein the default location and move R5.
" The release of X that you are installing does not include a server and you wish to leave
the current X installation undisturbed. An example of this would be the SGI Indigo, as no
R5 serverexists for this platform, but the R5 libraries and clients are useful.
The directory specified in ProjectRoot becomesthe root of the new installation, with the
normal directories underneath it. If it is set to /usr/XURS, this would be:

New Name Default Name Contents

lusrlXllR5/bin lusrlbinlXll Binaries

lusrIXllRSIlib lusrllib Libraries
lusrlXURSIliblXll lusrllib/Xll Fonts and support files
lusrlXllRSIinclude/Xll lusr/includelXl 1 Header files

8.5.1.3 The Platform Configuration File (platform.cf)

The platform-specific configuration file contains information specific to a certain platform or

type of machine. It changesthe default behavior of imake, as imake will make assumptions
unless told otherwise.* An example platform.cf file is sun.cffor Sun platforms, or sgi.cffor
Silicon Graphics platforms.
There may be other subtypes within the platform. For example, Sun3, Sun4, and Sun386i
machines are all describedwithin the sun.cffile. A file of this type should be all you need to
add when porting the X distribution to a new platform (other than new server code!).
Even though the platform has been narrowed down to a specific machine, there are still vari-
ables that could affect the installation process. Theseare:
" Operating system version. There are flags to describethe release of the OS you are run-
ning. You must change these flags if you are trying to building a version other than the
one describedin the MIT-supplied releasenotes.
#define OSName SunOS 4.1.2
#define OSMajorVersion 4
ttdefine OSMinorVersion 1

*The imakeprocesswouldhappilyconstructan Imakefileusinga genericsystem.In fact,if youeverseethatthege-

neric.cfhasbeenusedby imake,somethinghasgonewrong.

208 X WindowSystem Administrator'sGuide

 Any "features" specific to a releasecan be handled with conditional statements:
#if OSMajorVersion < 4 II (OSMajorVersion == 4 && OSMinorVersion < 1)
#define BootstrapCFlags -DNOSTDHDRS
#define StandardDefines -ENOSTDHDRS
#endif

Operating system-specific features. There may be common software features missing

on your vendor's release.Flags are provided to indicate their presenceor absence:

ttdefine HasVoidSignalReturn NO
#define SetTtyGroup YES
#define UnalignedReferencesAllowed NO
#define HasBsearch NO

" Build options. There are defaults for building the distribution on the optimal platform
(or the one they had handy at MIT).
#define XsunServer YES /* has color and mono support */
fdefine XsunMonoServer YES /* monochrome only */

" Hardware options. You may have different graphics hardware or a floating-point chip
that requires special treatment. In this example, the Sun3 (mc68000) processor has the
mc68881 floating-point chip, but the Sun compiler doesnot use it by default.
#ifdef mc68000
#define DefaultCCOptions -f68881 -pipe
#else
#define DefaultCCOptions -pipe
#endif

The -f68881 flag is meaningless on the sun4 platform, requiring the test for a sun3
(mc68000) platform.

You may wish to changethe following flags in the platform.cf file:

OSName This is full name of the operating system release.For example:
SunOS 4.1.1

OSMajorVersion
The "major" version number for the OS release (the number in front of the deci-
mal). The version flags should reflect the current system,as they will be tested
for later on in the platform.cffile. For example:
#if OSMinorVersion >= 1
#define HasBsearch YES
#else
#define HasBsearch NO
#endif

OSMinorVersion
The "minor" version number.

Building the X Window System 209

 OSTeenyVersion
A more preciseversion number for patch releasesof the OS.
BuildServer
This flag controls whether the server should be built along with the rest of the X
distribution. It is set to YES if the server exists; if a server doesn't exist for your
platform, it is set to NO. You can also set it to NO if you don't want to build a
server for some reason-for example, for the IBM RS/6000, the MIT serverruns
only on the Skyway display adaptor. If you do not have this particular board, you
should set the BuildServer flag to NO.

Server Options
Look for any server specific options. This could include monochrome and color
versions, as in:
#define XmfbpmaxServer NO
#define XcfbpmaxServer YES

8.5.2 Configuration Example 1

For this example, a Sun with limited available spacein limp is being used.The -temp= flag is
neededto specify an alternate directory for the temporary files from the compiler. See Sec-
tion 8.4.1.2 for more information on the -temp= flag.

The -temp= flag needs to be supplied on every cc command line used in the X build. This
means that it needs to make it into every Makefile used in the X distribution. You can accom-
plish this by editing the DefaultCCOptions parameter in the sun.cf file. (Being a very
system-specific flag, this parameteris specified in the platform.cf file, not in the site.def file.)
The README file in the mitlconfigl directory describes all of the configuration parameters,
including DefaultCCOptions:
DefaultCCOptions default special C compiler options

In sun.cf, DefaultCCOptions is currently specified with the following lines:

#ifdef mc68000
ttdefine DefaultCCOptions -f68881 -pipe
ttelse
ttdefine DefaultCCOptions -pipe
#endif

(The test for mc68000 is to add the flag for the mc68881 floating-point chip, available only
on the sun3 platform.)

If you enough spacein the area where you are building X, set the -temp- flag to the current
directory ("."). The C compiler will then use whatever directory it is invoked in for tempo-
rary files:
ttifdef mc68000
#define DefaultCCOptions -f68881 -pipe -temp=.
#else
#define DefaultCCOptions -pipe -temp=.
ttendif

210 X Window System Administrator's Guide

8.5.3 Configuration Example 2

In this example, the /6m.c/file is modified to overcome a permissionsproblem in AIX 3.1 on

the RS/6000 platform. The problem arises when the make install command is issued. The
chown program is executable only by root.* If you want to install X as an unprivileged user,
this will causethe iusrIucblinstall program to fail with the following error:
/usr/ucb/install: /bin/chown: cannot execute

The section of interest in the unmodified ibm.cfis the one specific to the RS/6000.(AIX runs
on several different platforms, including the PS/2, RT, and 370 systems.) The section we
want is surrounded by the test for RsArchitecture:

#ifdef RsArchitecture

#define OPERATING_SYSTEM AIX

ttdefine InstallCmd /usr/ucb/install
#include <ibmLib.rules>
#else

Redefine the InstallCmd parameter to the install.sh shell script that comes with the R5 re-
lease in the mitlutillscripts directory (the variable SCRIPTSRC is set to this).
#ifdef RsArchitecture

#define OPERATING_SYSTEM AIX

tfdefine InstallCmd sh $(SCRIPTSRC)/install.sh
#include <ibrnLib.rules>
#else

Since attempting to run the /bin/chown command will result in an error, the program run by
the install.sh script should be redefined to something harmless. All the program definitions
are at the top of the install.sh script:
# put in absolute paths if you don't have them in your path; or
fuse env. vars.

mvprog="${MVPROG:-mv}"
cpprog="${CPPROG:-cp}"
chmodprog="${CHMODPROG:-chmod}"
chownprog="${CHCWNPROG:-chown}"
chgrpprog="${CHGRPPROG:-chgrp}"
stripprog=" $ {STRIPPROG: -strip}"
mprog=" $ {RMPROG: -rm}"

You can just reset the CHOWNPROGenvironment variable to the /bin/true script, since all it
does is return a good exit status.
% setenv CHOWNPROG /bin/true

* chown returns an error if run by an unprivileged user on other systems, but on AIX 3.1 the executable has permis-
sions -r-x-- --, so that it can't be executed by others even long enough to get an error message.

Building the X Window System 211

 The install.sh program should then work when running make install as an unprivileged user:
% make install >& install.log

Since chown hasn't been run on any files, you will have to chown them later as root. SeeSec-
tion 8.4.3.1 for more information on touching up permissionsafter X is installed.

8.5.4 Configuration Example 3

If you are planning to add new fonts after installation, you may want to create a "local" di-
rectory that is always looked for by the X server. If this local directory is built into the X
server, userswill not have to manually modify the font path on the command line or in their
start-up files.
To find the correct flag, take a look at the config/README file:
DefaultFontPath default server font path

To find the current value, searchthe configlProject.tmpl file:

#define DefaultFontPath $(FONTDIR)/misc/,$(FONTDIR)/Speedo/,\
$(FONTDIR)/75dpi/,$(FONTDIR)/100dpi/

To override this definition, put your own version in configi'site.def:

#define DefaultFontPath $(FONTDIR)/local,$(FONTDIR) /misc/,\
$(FONTDIR)/Speedo/,$(FONTDIR)/75dpi/,$(FONTDIR)/100dpi/

The X server will not start if one of the directories in the default font path is missing a
fonts.dir file. The server will fail with the following error:
failed to set default font path '/usr/lib/Xll/fonts/local,/usr/lib/Xll/fo
nts/misc/,/usr/lib/Xll/fonts/Speedo/,/usr/lib/Xll/fonts/75dpi/,/usr/lib/X
ll/fonts/100dpi/'
Fatal server error:
could not open default font 'fixed'

To prevent this, copy in a least one font into the font directory and run mkfontdir.
# mkdir /usr/lib/Xll/fonts/local
# cd /usr/lib/Xll/fonts/local
# cp ~eap/home/xtrek.pcf .
# mkfontdir

8.5.5 Configuration Example 4

It's a good idea to keep vendor-supplied software separatefrom "local" software, such as the
MIT distribution. This will make software upgrades easier, as you are much less likely to
overwrite local changesif they are confined to a discrete area.

The X distribution is already installed in discrete areas,but the manpagesare generally in-
stalled directly into /usr/man. You may want to install the manpagesin lusrllocal!'man in-

212 X WindowSystem Administrator'sGuide

 stead. Most man commands will permit an alternate directory to be specified for searching
by setting the MANPATHenvironment variable:
% setenv MANPATH /usr/man:/usr/local/man

The man command will then searcheach directory in the order they appearin the MANPATH.
By default, MIT XI1 will install program manpagesin /usrlmanlmann and library manpages
in ImrlmanlmanS. Thesevalues are defined in configlProject.tmpl. In this example, the suffix
for client manpagesis changed from "n" to "1", and the "root" of the man directory structure
is changed from /usr/man to /usr/local/man. These should be specified in the config/site.def
file:

ttdefine ManSuffix 1
#define ManDirectoryRoot /usr/local/man

Program manpageswill now go in I usrI local!man/manl. Library manpageswill go in lusrllo-

callmanlmanS,where they are installed by default.

8.5.6 Configuration Example 5

If you know you will not be needing certain features of the distribution, you can suppress
their compilation using Boolean flags. The namesfor most of these flags start with the string
"Build":

% grep Build config/README I grep boolean

BuiIdFontServer boolean for building font server
BuildFonts boolean for building pcf fonts
BuildPex boolean for building all PEX-related code
BuildPexClients boolean for buildiing PEX clients/demos
BuildPexExt boolean for building PEX extension
BuildServer boolean for building X server
BuildXInputExt boolean for building X Input extension
BuildXInputLib boolean for building X Input library

These can be turned on or off in the configlsite.def file:

#define BuildPex NO
#define BuildXInputExt NO
#define BuildXInputLib NO

First check the configlplatform.cf file to see if their default value is changed for your specific
platform. Modifying these values can save a lot of compilation time and disk space if you
decide that you don't needto build a specific feature.

8.5.7 Other Build Flags

There are a number of compile-time flags that are not clearly documented in the release
notes. They may be in a [makefile or buried in the sourcecode.

Buildingthe X WindowSystem 213

8.5.7.1 xterm Build Flags

mill clients!xtermllmakefile contains the following comment:

/*
* add -DWTMP and -DLASTLOG if you want them; make sure that bcopy can
* handle overlapping copies before using it.
*/

You may want to enable these flags if you want userswho log into the systemusing xterm to
be recorded in the wtmp file. They will then appear when the last command is used. Change
the following line in mill clients!xtermllmakefile from:
MISCLDEFINES = /* -DALLOWLOGFILEEXEC */

to:

MISC_DEFINES = /* -DALLOWLOGFILEEXEC */ -DWTMP -DLASTLOG

8.6 Building Programs After X Is Installed

If you have people at your site who are going to be programming with X, you should supply
them with the proper tools to do this. This usually meansinstalling the libraries, header files,
and configuration files in a public area in the same manner as other programming environ-
ments. Even if you choosenon-standardlocations for the X distribution, the intake program
provides tools programmers can use without worrying about the location of the installed soft-
ware.

Appendix B shows how to compile an X program after X is already installed.

8.6.1 xmkmf

The xmkmf program is a shell script front end to the imake program, supplied in XI1R4 and
XI1R5. (See Section 8.7 for more information on imake itself.) It can be run in any directory
than contains an Imakefile. This could be within a subdirectory of the X distribution source
code or a program outside of it:
% xmkmf
mv Makefile Makefile.bak
imake -DUselnstalled -I/usr/lib/Xll/config

It first makes a backup copy of any existing Makefile, as it will create a new one with the
samename. It then invokes imake with the Uselnstalled flag, which tells imake that the
X distribution is installed and that it should use the header files and libraries on the system
instead of expecting ones to be present in the X source tree. For example, in config/Proj-
ect.tmpl:
#ifdef Uselnstalled
#define Phigslnclude -I$(INCDIR)
#else

214 X Window System Administrator's Guide

 #define Phigslnclude -1$(BUILDINCDIR)
#endif

This sequencemeans"use the system include file area if Uselnstalled is defined, other-
wise use the include files in the source code for PHIGS."

If you set ProjectRoot before the build, xmkmf will use the new root directory. For ex-
ample, if you set ProjectRoot in site.def before installation:
#ifdef ProjectRoot
#undef ProjectRoot
ttendif
#define ProjectRoot /usr/XHR5

Running xmkmf would produce:

% xmkmf
mv Makefile Makefile.bak
imake -DUselnstalled -I/usr/XllR5/lib/Xll/config

xmkmfuses the -/ flag to tell cpp where to look for include files. The include files in this case
are the imake configuration files. The default location for installing these files is
lusr/lib/Xlllconfig. If you have your own private set of configuration files, you can invoke
imake with a different include directory:
% imake -DUselnstalled -I/home/eap/myconfig

In R5, xmkmf also takes an -a flag, which executesthe normal make targets automatically:
% xmkmf -a
mv Makefile Makefile.bak
imake -DUselnstalled -I/usr/lib/Xll/config
make Makefiles
make includes
make depend

The Makefiles target will recursively build any Makefiles that may be presentin subdirec-
tories. The includes and depend targets are used to build a list of dependenciesthat are ap-
pended to the Makefile. These will force recompilation of the target if something related to
the program changes elsewhere.

8.6.2 Include Files

Include or "header" files should be found automatically by the preprocessor,as they are
stored in standard system directories, such as Iusrlinclude. Note that MIT supplied header
files will have the XI1 directory already prependedto the name of the include file:

Mnclude <Xll/Shell.h>

or even a subdirectory within XI1:

#include <Xll/Xaw/Box.h>

Building the X WindowSystem 215

 cpp will interpret the complete path, for example, as ImrlincludelXlllXawlBox.h. If you
wish to bury the include files in another subdirectory, you will still need to have the last di-
rectory named XI1, as in lusrlXllR5lincludelXll. cpp would then be invoked with
-IlusrlXllR5/include. You could also cheat and create a symbolic link from XI1 to the in-
clude file directory:
# In -B Xll .

This would keep cpp happy when it looks for the files. It is often desirable to keep the MIT
headersseparatefrom the systemheaders,as this will keep them from being damagedduring
OS upgrades.

8.6.3 Libraries

The X libraries will usually be installed in lusrllib, but there are several reasonsto install
them in an alternate location. In any case, the Makefiles generated by imake should do the
right thing if you configured the X distribution this way. Alternate library locations can be
specified with the -L option. If you have Project Root set to lusr/XllR5, the X libraries
wi\\bem/usr/XUR5/lib.

8.7 More About imake

This section describes the configuration processin more detail and may help if you encoun-
tered a problem with your X build.
imake is a project managementtool that is used for building the X Window System from
source code. This section describes imake in the context of building Xll, but imake can be
used for any large project that is going to be compiled on more than one type of platform. In
particular, it is the tool of choice for public domain X programsthat are distributed in source
form. SeeAppendix B for more information on compiling public domain software.
imake uses a combination of make and the C preprocessor (cpp). A basic understandingof
each is required to intelligently configure the X build process.

8.7.1 The make Program

The make program is the default UNIX tool for maintaining source code. It usesa configura-
tion file called Makefile to describe each component of the source distribution, how each
should be compiled, and how individual files relate to one another. It savestime and effort by
automating common programming tasks. For example, if a headerfile has beenmodified, any
program that usesit is recompiled, ensuring that everything is up to date.*

*See the Nutshell Handbook Managing Projects with make (O'Reilly & Associates, 1991) for more information on
the make program.

216 X WindowSystemAdministrator'sGuide
 The XI1 distribution has been ported to many different platforms, with each one requiring its
own particular flags and libraries to compile programs. For example, the Sun C compiler
may require one set of flags:
cc -c -0 -pic

While the MIPS C compiler needs a different set:

cc -O -prototypes -float -cckr -Wf,-XNh2000

The usual way to handle this is to put all known options in a Makefile, and rely on the person
compiling the program to figure out what options or flags should be enabled.
For example, a well-commented Makefile might read something like the following:

# Define the other compilation flags.

# Add -DBSD4_2 for 4.2bsd systems.
# Add -DSYSV for System V.
# Add -DSYSV -D_SVR3 for SCO ODT, ISC Unix 2.2 or before,
# or any System III Unix, or System V release 3-or-older Unix.
# Add -DSVR4 (not -DSYSV) for System V release 4.
# XCFLAGS can be set from the command line.
CFLAGS=-0 $(XCFLAGS)

This approach works fine for simple programs, but make is insufficient for maintaining the
large number of libraries and clients that make up the X distribution. The XI1 core distribu-
tion alone has several hundred Makefiles, and editing each one of these Makefiles by hand
would be absurd.

Some large packages,such as TeX, use make's ability to recursively invoke itself in subdirec-
tories, make flags are passeddown the directory structure by specifying the flag on the com-
mand line, with each Makefile inheriting the flag's value from the previous invocation of
make. This is shown in Figure 8-3.

This approach works for flags, but complicated make commandsmust still be edited by hand
in each Makefile.

Thus enters imake. The main function of imake is to "automatically" generateany number of
Makefiles from one set of configuration files. It may help to call the imake program a "text
filter," as all it really does is take a set of text files as input and create a text file as output. As
input, imake uses a set of files in a configuration directory (such as lusrlliblXlllconfig} and a
file in the current directory called Imakefile. As output, imake generatesa Makefile.

8.7.2 The C Preprocessor

imake relies on the C preprocessor(usually named cpp}. cpp provides a macro facility and
conditional expressions. If you know how the C preprocessorworks, then you have a good
chanceof understandingof how imake usescpp syntax.

Buildingthe X WindowSystem 217

 UNIXfilesystem /

" Makefile
CFLAGS= -0 -I/usr/include/Xll

" Makefile
CFLAGS= $(CFLAGS)

" Makefile
CFLAGSr $(CFLAGS)

Figure 8-3. Recursive make

For a simple example of cpp syntax, examine the following lines:

ttifdef BSD
#define CCOPTS -DBSD
#endif /* BSD */

The #ifdef line, coupled with the #endif line, is an example of a conditional. Theselines
say that if the BSD variable is defined, then set the CCOPTS variable to "-DBSD." Similarly,
you can use #if ndef to set up a negative conditional. For example:

#ifndef CppSedMagic
#define CppSedMagic sed -e '/A# *[0-9][0-9]* *.*$$/d' \
-e VAXCOMM$$/s//#/' \

#endif /* CppSedMagic */

The lines between the #ifndef and #endif are executed only if the specified variable
(CppSedMagic) is not currently defined. These lines say that if the CppSedMagic vari-
able is not defined, then define CppSedMagic as instructed.

The second example also shows an example of a macro. Any subsequentoccurrence of

CppSedMagic is replaced by the multi-line sed expression.
This construction of defining a macro only if it isn't already defined is quite common: cpp
will complain if you try to redefine somethingthat is already defined.

218 X Window System Administrator's Guide

 8.7.3 Imake Syntax

cpp does not do anything except process text files: it cannot invoke other programs, make
can actually do work, but it lacks the ability to test the value of a variable, making it inflex-
ible. What imake does is combine the best features of cpp and make. The real value of imake
is that it allows easycreation of Makefiles under changing conditions.
The syntax used by imake is based on syntax used by both cpp and make. When cpp and
make syntax are inconsistent with one another (or when different versions of cpp are incon-
sistent with each other), imake needs to become the arbiter. This is most apparent when it
comes to interpreting comments,defining multi-line macros,concatenatingmacros,and deal-
ing with tabs.

8.7.3.1 Comments in imake

The make program expects comments to be preceded by the "#" character. The problem is
that "#" indicates the start of a preprocessordirective (a cpp command) to cpp.
For example, if you had the following make-style comment in a file called testfile:
# All rights reserved.

If you run this file through the cpp program, you'll get an error message:
% /lib/cpp < testfile
# 1 ""
1: undefined control

cpp complains that it does not recognize whatever followed "#" as a valid cpp command.*
You may see C-language style comments in imake configuration files. For example:
/*
* Concat - concatenates two strings.
*/

The "/**/" construction will work fine, but beware that the comment will be removed by
the cpp program and never seenagain. The comment will not appearin any /mafce-generated
Makefiles. If you want your commentsto appearin any Makefiles, you'll have to use an al-
ternate comment mechanism:

" One way to protect the make comment from cpp is to put a "null" C-style comment in
front of it:

/**/# All rights reserved.

cpp strips out the / * * / comments and passesthe rest of the line to the Makefile un-
touched:

% /lib/cpp < testfile

# 1 -"
# All rights reserved.

*Even worse, if the first string following the "#" is a valid cpp command (such as #if or #def ine), cpp will inter-
pret it and generate a useless Makefile.

Building the X WindowSystem 219

 The make commentnow survives its passthrough cpp.
Now that ANSI C preprocessorsare now becoming common, this can no longer be relied
upon, as ANSIC will try to interpret even though it has a C comment in front of it.
In R5, a cpp-proof comment prefix XCOMM is provided as a convenience. If you put the
string XCOMMin front of comment text, imake will do the right thing with it. For example:
XCOMMAll rights reserved.

Will generateinto the resulting Makefile:

# All rights reserved.

8.7.3.2 Multi-line Macros (@@)

Some of the cpp macros used in the imake configuration files are quite complex and may ex-
pand into multi-line make commandslater on. The default behavior of cpp is to collapse ev-
erything within a macro definition (anything following a #def ine) into a single line. To
protect the macro's line breaks from cpp, the "@@" syntax is used.The imake program will
replace all of the "@@" sequenceswith the newline character,preserving the structure of the
make command.

For example, the following multi-line macro appearsin an imake configuration file:
#ifndef InstallNonExec
ttdefine InstallNonExec(file,dest) @@\
install:: file @@\
$(INSTALL) -C $(INSTDATFLAGS) file $(DESTDIR)dest
#endif /* InstallNonExec */

If this is used in an Imakefile:

InstallNonExec (system. twmrc, $ (TWMDIR) )

It would be expanded later on into:

install:: system.twmrc
$(INSTALL) -c $(INSTDATFLAGS) system.twmrc $(DESTDIR)$(TWMDIR)

This is a valid multi-line make command.

If the "@@" marker was not used,it would be squashedinto a single line by cpp:
install:: system.twmrc $(INSTALL) -c $(INSTDATFLAGS) system.twmrc $(DESTD
IR)$(TWMDIR)

This will causestrangeerrors from make:

% make install
make: Warning: Infinite loop: Target vinstall' depends on itself
make: Fatal error: Don't know how to make target "-c1

220 X Window System Administrator's Guide

8.7.3.3 Concatenating Macros

A common trick is to use the null comments "/**/" to concatenatemacros or strings within
cpp. For example, if you had a file called testfile containing the following:
#define MYTOPDIR /usr/
#define XLIBDIR lib/Xll/
#define FONTDIR fonts/

You may want to concatenatethese strings into one. If you try concatenating them directly,
such as:

MYTOPDIRXLIBDIRFONTDIR

cpp will respond by trying to expand the entire string. Since the string is not defined, it will
return the string itself, which is hardly what you want.
% cpp testfile
# 1 "testfile"

MYTOPDIRXLIBDIRFONTDIR

You can get around this with some versions of cpp by separating each component with null
comments.The comments prevent the components from being interpreted as a single string.
For example:
MYTOPDIR/* */XLIBDIR/* */FONTDIR

With the commentsinserted, passingtestfile through some versions of cpp yields:

% cpp testfile
# 1 "testfile"

/usr/lib/Xll/fonts/

This works great. But the problem with this trick is that ANSI C preprocessorshave a differ-
ent and incompatible syntax for concatenation. Under an ANSI C preprocessor,the preceding
example fails to concatenate.The null comments are expanded into white space,which is di-
sastrous in this example:
% acpp testfile
# 1 "testfile"

/usr/ lib/Xll/ fonts/

ANSI C uses the "##" sequence for concatenation. For example:

MYTOPDIR# #XLIBDIR# #FONTDIR

Running this through an ANSI C preprocessoryields the correct value:

% acpp testfile
# 1 "testfile"

/usr/lib/Xll/fonts/

Building the X Window System 221

 To concatenatemacros within imake, imake provides the Concat and ConcatS macros which
do the right thing depending on what type of preprocessoryou use. In this case, since we
have 3 arguments,we use ConcatS:
Concat3 (MYTOPDIR,XLIBDIR,FONTDIR)

8.7.3.4 Dealing with Tabs

In someversions of cpp, tabs are converted to spacecharacters. The make program, mean-
while, requires tab charactersto precedethe commandsin a make rule. So if a version of cpp
that converts tabs to spacesis used on a Makefile, make will bomb out with an error such as:
% make
make: Fatal error in reader: Makefile, line nn: Unexpected end of line seen

The imake program therefore tries to intelligently place the tab characters back in the
Makefile after being processedby cpp. If the version of cpp that comes with your system is
unsuitable for building the X distribution, the contrib area provides a replacement in con-
triblutillcpp.

8.7.4 imake Configuration Files

imake usesa seriesof configuration files when creating Makefiles for a particular package.
First, it uses a series of system-wide imake configuration files, found in the directory
lusrlliblXlllconfig. In addition, imake looks for a file named Imakefile in the directory it is
being invoked in, which definesparametersspecific to that particular package.
This discussion will be much easier to follow if you have these files online and available to
browse through while reading. If you have the X distribution source code available, look in
the directory mitlconfig. If the distribution is already installed, look in the directory
lusrlliblXlllconfig.
This looks very complex-it is. However, you should be relieved to know that any changes
you make are confined to one file (unless you need to do something more complex, such as
add supportfor a new platform).
The filenames indicate the function of the file in a general manner. Files ending in .tmpl are
template files. They are like templates in that they provide a structure that is "generic" and
later customized to a specific result. Files ending in .c/are configuration files, used to config-
ure imake for a specific platform. Files ending in .rules contain make rules that describehow
make should build programs and what files dependon the others.
One convention to keep in mind while browsing the files is that cpp macros are mixed-case
(for example, InstallAppDefaults), and make flags are uppercase (for example,
INSTKMEMFLAGS).

222 X WindowSystemAdministrator'sGuide
8.7.4.1 A Quick Tour of Files Used by imake

imake
1I Imake.
tmpl:
global constants
header blocks

#include <platform.tf>

#include <site.def>

system description and

build
definitions PH./Makefile
J
#include <Project.tmpl>

#include <lmake.rules>

#include "./(makefile"

extra make rules

Figure 8-4. Files processed by imake

The following is a vastly simplified outline of the files used by imake, in the order in which
they are used.Figure 8-4 demonstratesthe useof thesefiles.
" Imake.tmpl is fed to cpp and it usesthe ttinclude mechanismto incorporate the other files.
It provides default values and a template for the generatedMakefile.
" platform.cf overrides the default values and configures imake for a specific platform. (An
example of aplatform.cf file might be sun.cfor ibm.cf.)

" site.def provides another place to override default values, but on a site-wide basis, which
could include more than one platform.
" Project.tmpl is where imake is configured for building XI1, the "project" in this case.
Other imake files should be generic, isolating the XI1-specific information to this file.
" Imake.rules contains generic rules for generating components of any build, such as li-
braries and executables.

" /makefile is the per-directory file that controls the operation of imake in the current direc-
tory.

There are certain platforms that require lots of platform-specific rules (they are usually for
building shared libraries). To isolate these cases,there are separate.rules and .tmpl files that
are included when a build is performed for the platform. For example, the files ibmLib.rules
and ibmLib.tmpl are used by imake on the ibm platform.

Building the X Window System 223

8.7.5 Using imake to Build X11

You rarely ever need to run the imake program directly. It is usually run by the Makefile at
the top level of the XI1 sourcetree when the make command is used.
The usual thing to do when building X is to type:
% make World

If this fails with an error message such as:

*** Error code 1

make: Fatal error: Command failed for target "subdirMakeflies'
Current working directory /eap/XHR5/src/sun4_412
*** Error code 1
make: Fatal error: Command failed for target "Makefiles'
Current working directory /eap/XHR5/src/sun4_412
*** Error code 1
make: Fatal error: Command failed for target "World'
Current working directory /eap/XHR5/src/sun4_412
*** Error code 1
make: Fatal error: Command failed for target "World'

You will have to figure out what went wrong and correct it. After you have done this, you
may be able to save sometime by using a target other than World. A target is a specific task
within a Makefile. The top-level Makefile has several targets:
Makefiles This target creates a Makefile in any subdirectory that contains an
Imakefile. You should run this anytime you change a configuration option.
clean This target "cleans" or removes all the object files and libraries from the
sourcetree. You should use this if you fail miserably and want to start over
again.

includes This target creates symbolic links from the current directory to where the
include files are stored in the source tree. It should be used before the
depend target.

depend This target generatesdependencyinformation for make. A program called

makedependis invoked, which searchesall the source files for ^include
statementsand builds a list that is appendedto the Makefile. For example:

Tekproc.o: /usr/include/fcntl.h /usr/include/sys/fcntlcom.h

Tekproc.o: /usr/include/sys/stat.h /usr/include/unistd.h
Tekproc.o: /usr/include/sys/time.h /usr/include/sys/time.h
Tekproc.o: ../.././Xll/Xatom.h ../.././Xll/cursorfont.h
Tekproc.o: ../.././Xll/StringDefs.h ../.././Xll/Shell.h
Tekproc.o: ../.././Xll/Xmu/CharSet.h /usr/include/stdio.h

This should be run every time a Makefile is rebuilt.

World This is the primary target for building the distribution. It runs make with
the following targets: Makefiles, clean, include, dependand then with just
with the -k option. (Keep in mind that -k tells make to keep running even

224 X Window System Administrator's Guide

 if there are errors in the build process.) You probably only needto run this
the first time you try to build on a new platform, as it will delete any previ-
ous effort to build the distribution.

Everything This is similar to World, but it will only rebuild files that are out of date
according the to the make rules. You should use this if you change any of
the configuration files, as it will rebuild all the Makefiles. This is also
smart to run after applying a patch, as the patch may modify something in
the configuration area.
install This target installs binaries, libraries, include files, and support files. The
target will be affected by flags such as InstallAppDefFiles, In-
stallFSConf ig, and InstallXdmConf ig.

install .man This target installs the manual pages. Flags such as ExpandManNames
and InstallLibManPages will affect this target.
As you can see in the examples below, targets end in a double colon (::). By using the double
colon, make allows the target to appearmore than once in the Makefile. For example, there
are two install targets in the following Makefile:

install:: $(PROGNAME).ad
@if [ -d $(DESTDIR)$(XAPPLOADDIR) ]; then set +x; \
else (set -x; $(MKDIRHIER) $(DESTDIR)$(XAPPLOADDIR)); fi

install::
@case '${MFLAGS}' in *[ik]*) set +e;; esac; \
for i in $(SUBDIRS) ;\
do \

Both will be executed when a make install is performed.

A handy option to make is the -n option. The -n option shows all of the expected make output
without actually executing the commands,so you can see where files are going to be installed
before you actually install them:
% make -n install
install -c xrn /usr/bin/Xll
install -c -m 0444 XRn.ad /usr/lib/Xll/app-defaults/XRn
echo "install in . done"

The -n option can avoid unpleasant surprises, such as accidentally overwriting something
previously installed.
If you manageto destroy the top level Makefile (mitIMakefile), you can recover:
% cp Makefile.ini Makefile

This gives you a Makefile that can "bootstrap" the build from this point on.

Building the X WindowSystem 225

 8.8 Porting Hints

Here are some techniques that may be helpful when trying to build the distribution on plat-
forms that are slightly different from the onesdescribed in the MIT releasenotes.

8.8.1 Undefined Symbols or Functions

You will occasionally get errors when compiling or linking X programs. This is more likely
to happen on platforms that are not listed in the release notes, but there will be times when
errors occur on the supportedplatforms. This is especially likely to happen if your platform is
slightly newer or older than the one describedin the releasenotes; it is not unusual for ven-
dors to change the location of header files between operating system releases, or to delete
support for old devices in new releases.For example, the file pmioctl.h was in the directory
Iusrlincludelmachine! in Ultrix 3.1, but moved to Iusrlinclude!ioltcl in Ultrix 4.0. The fix is
often trivial, though, so don't give up in despair.

8.8.1.1 Missing Header Files

If the compiler dies with an "undefined symbol" or "no declaration" error when compiling C
sourcecode, try searchingthe system headerfiles for the missing symbol:
% find /usr/include -type -f -exec grep symbol /dev/null '{}' ';'
... any matches will appear here ...

(We grep through /dev/null to trick grep into reporting the name of the file that contained the
symbol.)

If you find the symbol in a new location, edit the #include line to reflect the new location.

8.8.1.2 Missing Function Definitions

If the loader dies with an "undefined symbol" error when linking a binary:
Id: Undefined symbol
_XtUnmanageChiId
_XtOpenDi splay
_XtCreateApplicationContext
_XtDispatchEvent
_XtParent
_XtToolkitInitialize

You can make an informed guess that the missing library is the X Toolkit (called with
'-iXt"), as the function names start with "Xt". If the correspondinglibrary is not obvious,
try searching the system libraries for the symbol. The nm program can be used to list all the
symbols presentin a library or object file. The output of nm is very system-specific,but under
SunOSit might produce something like the following:

226 X Window System Administrator's Guide

 % nm /usr/lib/libc.a
ftime.o:
U .div
00000000 T _ftime
U _gettimeofday
nice.o:
U _errno
U _getpriority
00000000 T _nice

The output displays all symbols that are used in the library, with a "U" if the symbol is only
referenced, and a "T" if the symbol is defined.

To quickly find the library containing the symbol, automate the searchprocess. For example,
if the loader complained that the symbol "dlopen" is undefined, you could searchall li-
braries in iusrllib with the following csh script:
% foreach I (/usr/lib/lib*)
? echo $1
? nm $1 I grep dlopen
? end

As output, you'll get the namesof the listed libraries with any matching lines in between:

/usr/lib/libcurses_p.a
/usr/lib/libdbm.a
/usr/lib/libdl.so.1.0
00000020 T _dlopen
/usr/lib/libfVVplot.a
/usr/lib/libg.a
/usr/lib/libkvm.a '

In someversions of nm, there may be options that simplify the search.The SunOSnm has the
-o option for printing the library name and the -g option for printing only "global" symbols:
% nm -og /usr/lib/lib* I grep dlopen
nm: /usr/lib/lib.b: bad format
/usr/lib/libdl.so.1.0:00000020 T _dlopen
nm: /usr/lib/libm.il: bad format

In this example the script has found the "dlopen" symbol defined in the library
lusrllibllibdl.so.1.0.

Once the new library is found, you can add it to the Imakefile for that directory, or you can
add it system-wide in the platform.cf file. If the function is needed for the entire build, it's
preferable to enter it into a system-wide file so that all future Makefiles generatedby imake
or xmkmf will automatically have the library included.

Building the X WindowSystem 227

8.8.2 Searching for Preprocessor Symbols

An important feature of cpp is that it can tell other programswhat type of platform it is being
executed on. cpp provides pre-defined symbols indicating the platform, operating system,
byte order, processortype, and type of C compiler. Some of these symbols are shown in the
following table.

Table 8-1. cpp Symbols

Symbol Type Examples

Architecture mc68k, i386, i8086, iAPX286, spare
OS unix, DGUX, M_XENIX, UTS, ultrix, venix, xenix
Byte Order MIPSEB, MIPSEL
Type sun3, sun4,sun386,ns 16000,ns32000,mips
Compiler _POSIX_SOURCE, ANSI, __STDC__,_ANSI_C_SOURCE,
_NO_PROTO

imake uses these symbols to automatically determine what type of platform it is being run
on.* So one of the first tasks of porting X to a new platform is to find a unique preprocessor
symbol so that imake can determine the type of platform. On some systems the
BOOTSTRAPCFLAGS flag will have to be used for this function, but it's worth checking first.
The following are hints about where to check:

1. The manual pages for the preprocessorand the compiler are the first places you should
check. Beware that the names of the compiler programs vary. For example, the C com-
piler on the IBM RS/6000 is called xlc. There may be several different versions of the
compiler available, each with its own behavior. It is not unusual to have an ANSI C and
"K&R" C compiler on the samesystem. There may be more than one version of cpp as
well-for example, IRIX has both cpp and acpp. Not surprisingly, some vendors do not
list all the predefined flags and you will have to hunt for them.
2. See if the compiler or preprocessorhas a "verbose" flag, usually -v or -verbose. This flag
shows which flags are being passedto the preprocessor(where they are interpreted):
% cc -v -E foo.c > /dev/null
/lib/cpp -undef -Dunix -Dsun -Dsparc foo.c

From this, you can determine that the flags unix, sun, and spare are defined by the
preprocessor. The -E flag means "run the preprocessor only," and the output of the
preprocessoris discardedinto /dev/null.

*Somesystemshaveno uniquepreprocessor
symbols,requiringyouto tell imakethetypeof platformwhenit is first
invoked.

228 X WindowSystem Administrator'sGuide

3. If the previous methods fail, it may require a low-tech approach. In most cases, this
means the strings program. The strings program reports all printable strings in a binary
file:

% strings /lib/cpp

too many -I options, ignoring %s

cpp internal bug alert, readmit (argvO) , argvO=NULL
%s.init
unix
m68k
_SYSV_SOURCE
_BSD_SOURCE
_AUX_SOURCE
/usr/include
/usr/include
%s: %s

Experience would tell you that the strings clustered around unix are likely suspectsfor
preprocessorsymbols. You can test them by running them through the preprocessorand
checking to seeif they are defined. First, enter into a file the symbolsyou wish to test:
% cat > foo.c
unix
m68k
_SYSV_SOURCE
_BSD_SOURCE
_AUX_SOURCE
/usr/include

Then run the preprocessor on them:

% cc -E foo.c
# 1 "foo.c"
1
1
1
I
I
/usr/include

Any symbol that evaluated to "1" is being defined by the preprocessor.The "/usr/in-
clude" is unchanged,showing that it does not mean anything special to the compiler.
(The line starting with the "#" character is a line number inserted by the preprocessor
showing its position in the C sourcefile.)

Beware that symbols may not be unique to a platform and BOOTSTRAPCFLAGS may have to
be specified after all. For example, both Sequent and Encore define ns32000 on their
machines. You would have to specify a unique symbol on the command line for the initial
make:

% make World BOOTSTRAPCFLAGS="-Dumax"

Building the X Window System 229

 The symbols can be addedto the file mitlconfiglimakemdep.h. Look at the top of the file for
directions on how to define new symbols:

Step 1: imake_ccflags
Define any special flags that will be needed to get imake.c to conpile.
These will be passed to the conpile along with the contents of the
make variable BOOTSTRAPCFLAGS.
i

Follow the stepsdescribedin the file to add information specific to the new platform.

8.9 Related Documentation

You should read the Release Notes before doing anything. The text version is mitlREL-
NOTES.TXT and the PostScript version is mitlRELNOTES.PS.
There are severaldocumentsthat explain imake in more detail. They include:

" The imake manual page (millconfiglimake.man).

" "Configuration Managementin the X Window System," by Jim Fulton. In the sourcedis-
tribution, you can find this in the file milldoclconfiglusenixwslpaper.ms.
" "The X User: Demystifying Imake," by Paul Davey, published in The X Resource,Issue
2, O'Reilly & Associates, Inc., Spring 1992.

" "Using Imake to Configure the X Window System," by Paul Dubois. Available via anon-
ymous/?;?fromftp.primate.wisc.edu in the directory pub/imake-stuff.
The flags usedin the configuration process are listed in mitlconfigl'README.
Documentation for porting the X server is contained in the miti'doc/'Serverand mit/hard-
copy/Server directories.

NFS administration is described in Managing NFS and NIS, by Hal Stern (O'Reilly & Asso-
ciates, 1991).

The make program is describedin Managing Projects with make, by Andrew Oram and Steve
Talbott (O'Reilly & Associates, 1991).

"The X Administrator: Building XI Ir5 in Limited Disk Space," by Adrian Nye, published in
The X Resource,Issue 0, O'Reilly & Associates,Inc., Fall 1991.

230 X Window System Administrator's Guide

 Useful Things to Know

This appendix covers "miscellaneous" topics that either didn't fit cleanly into
any other chapter, or fit into so many that we found ourselves repeating our-
selves all the time.

In This Appendix:
The comp.windows.x Newsgroup 233
How to ftp a File 234
Getting Files Using ftpmail 235
BITFTP 237
The xstuff Mail Archive Server 237
Unpacking Files 238
Making a Filesystem Available via NFS 239
How to Add a Host 239
Adding a Host to /etc/hosts 239
Adding a Host Using NIS 240
Adding a Host Using DNS 240
Adding an Ethernet Address 242
Printing Documentation in the MIT X Distribution 242
Converting a Number Into Hexadecimal and Back 243
Configuring a Sun as an X terminal 243
Using More than One Frame Buffer Under SunOS 244
 A
Useful Things to Know

As we wrote this book, we found that there were a lot of odds-and-ends that didn't fit into
any chaptersbut were too important to leave out. This appendix was devised as a "catch-all"
for miscellaneous information.

A.1 The comp.windows.x Newsgroup

comp.windows.xis a Usenet newsgroup dedicated to the X Window System. You can use it
reach thousandsof X programmersand users. You would normally use a newsreader such as
rn, v/7,AT/?,or readnews to read the group. If you do not have Usenet access at your site, you
can still reach the newsgroupthrough e-mail. To requestthat you be addedto the list, send a
polite message to [email protected] send mail to the entire list, use
[email protected].

In addition to comp.windows.x, there are also newsgroups for comp.windows.x.motif,

comp.windows.x.intrinsics, comp.windows.x.apps, and comp.windows.openlook. Each of
these newsgroups maintains a Frequently Asked Questions list, or FAQ, which contain a
wealth of information on X. comp.windows.x.announce is a newsgroup dedicated to
announcementsabout X, for example, announcementsof new patchesbeing released.
For more information on Usenet, see Managing UUCP and Usenet by Tim O'Reilly and
Grace Todino (O'Reilly & Associates,Inc., 1992). Using UUCPand Usenet by Grace Todino
and Dale Dougherty (O'Reilly & Associates, Inc., 1991), and The Whole Internet User's
Guide & Catalog by Ed Krol (O'Reilly & Associates,Inc.. 1992).

Useful Things to Know 233

A.2 How to ftp a File

If you've neveranonymous
ftp'd a file before,a goodfile to startwith is thecomp.windows.x
FAQ from export.lcs.mit.edu.
The first thing you do is connect to the site.
lmui@opal% ftp export.lcs.mit.edu
Connected to export.lcs.mit.edu
220 export.lcs.mit.edu FTP server (NEWS-OSRelease 4.1C) ready.
Name (export.lcs.mit.edu:lmui):

By default, \hzftpd assumesthat you have an account on the remote machine, so if you press
RETURNit will try to log you in under that name. Since you probably don't have an account
on this machine, you don't want to pressRETURN,but instead type in the name anonymous.
Name (export.Ics.mit.edurlmui) : anonymous
331 Guest login ok, send ident as password.
Password:

For your password, type in your e-mail address.(If you don't enter your e-mail addressit
may still let you in, but it's "good manners" to identify yourself properly when using some-
one else's machine.) Don't type your real password here!!!
Password: Imui&ora. com
230 Guest login ok, access restrictions apply.
ftp>

You are now logged in. (Note that although I typed my e-mail address at the Password
prompt, it wouldn't actually be shown).

From here, there is a small set of commands you can run. Do a help at the f tp> prompt to
see a list of commands. For browsing directories, use the commandscd and Is. The dir com-
mand is also commonly available for long listings.
In this example, we want the FAQ from the contrib directory. So first cd to that directory and
then do a dir to make sure that the file is there:

ftp> cd contrib
250 CWD command successful.
ftp> dir *FAQ*
200 PORT command successful.
150 Opening data connection for /bin/Is (ascii mode) (0 bytes).
-rw-r-r- 1 ftp ftp 213297 Aug 3 12:09 FAQ
-rw-r-r- 1 ftp ftp 35742 Aug 5 17:10 FAQ-Xt
-rw-r-r-- 1 ftp ftp 16985 Aug 5 17:10 FAQ-Xt.Z
-rw-r-r- 1 ftp ftp 97671 Aug 3 12:09 FAQ.Z
-rw-r-r- 1 ftp ftp 169388 Jul 20 05:46 Motif-FAQ
226 Transfer complete.
remote: *FAQ*
311 bytes received in 0.062 seconds (4.9 Kbytes/s)
ftp>

(This ftp server understoodmy asterisks as wildcards, but not all do.) You probably want to
get the compressedFAQ since it will transfer much faster.Turn on "binary" mode for binary
transfer and use the get command to get the file:

234 X WindowSystemAdministrator'sGuide
 ftp> binary
200 Type set to I.
ftp> get FAQ.Z
200 PORT conmand successful.
150 Opening BINARY mode data connection for FAQ.Z (84245 bytes).
226 Transfer complete.
local: FAQ.Z remote: FAQ.Z
84730 bytes received in 16.87 seconds (4.91 Kbytes/s)
ftp>

The file should now be in whatever directory you ran ftp from. Note that if you had another
file in this director}' called FAQ.Z,it would be overwritten even if you had the csh noclobber
variable set.

For getting multiple files, use the mget command. (Use the prompt command first to toggle
being askedto confirm each file transfer.)
If you are done with your ftp session,use the quit command to exit ftp.
ftp> quit
221 Goodbye.
lmui@opal%

A.2.1 Getting Files Using ftpmail

ftpmail is a mail server available to anyone who can send and receive electronic mail to and
from Internet sites. This includes most workstations that have an e-mail connection to the
outside world, and CompuServe users. You do not need to be directly on the Internet to use
ftpmail.

Sendmail to the ftpmail server, [email protected]. There are a set of commandsthat

the server understands; to get a complete help file, send a message with no subject and the
single word "help" in the body.
The following is an example mail sessionthat will get you the comp.windows.* FAQ.
lmui@ruby 145% mail [email protected]
Subj ect:
reply [email protected]
connect export.lcs.mit.edu
chdir /contrib
binary
uuencode
get FAQ.Z
quit
lmui@ruby 146%

The reply line is specified to ensure that the correct return addressis used.Without this line,
ftpmail will mail the file to whatever return addressis in your mail header, which may be
wrong.

The connect line is required to tell ftpmail what host to connect to. In this case, we set it to
export.lcs.mit.edu. By default, ftpmail logs in as anonymous; you could actually supply a
user name and passwordhere if you had an account on the machine in question.

Useful Things to Know 235

From here on, we ask to chdir to the Icontrib directory, set up binary transfer, uuencode file
transfers,get the FAQ.Z file, and quit. A signature at the end of the messageis acceptableas
long as it appearsafter "quit." The ftpmail daemon quickly replies with a messageconfirm-
ing that your request is in the queue, and telling you how many requestsare in front of yours
and how your message will be executed.

When the job finally goes through, all retrieved files will be split into 60KB chunks and
mailed to you. In addition, you'll receive a messagetranscribing the activity.
lmui@ruby 120% mail
Mail version SMI 4.0 Wed Oct 23 10:38:28 PDT 1991 Type ? for help.
"/usr/spool/mail/lmui" : 10 messages

6 [email protected] Wed Aug 26 21:24 822/50654 part 001 of FAQ.Z (/contr

7 [email protected] Wed Aug 26 21:24 821/50633 part 002 of FAQ.Z (/contr
8 [email protected] Wed Aug 26 21:24 573/35113 part 003 of FAQ.Z (/contr
9 [email protected] Wed Aug 26 21:25 43/1466 results of ftpmail reques

&

Savethe files togetherand exit mail:

& save 678 FAQfile
"FAQfile" [New file] 2216/136400
& q
Held 7 messages in /usr/spool/mail/lmui

Now, remove the mail headers. The file should start with the word "begin," and end with
the word "end", with lines of gibberish in between:
begin 644 ftpmail. uu
M' YV03LK<F7-&SILZ< .;H^#' F3lLX+NZD<4/FS4 V7>%BX$3C' 11@W<~Z4D3- '
MP90Z8M24&4-G8<. '$2=60(@'A! $Y9>+4*>.&#IL\ ( (+, 65. &# (@H./V?02?,&

5^PT2=0$GV"-D!%VD&B">Q(1@)G@2

end

Next, uudecode the file as shown in Section A.4.

lmui@ruby 125% uudecode FAQfile

uudecodecreatesa file called ftpmail. uu with permissions644:

litiui@ruby 126% Is -1 ftp*
-rw-r- r-- 1 Imui 97671 Aug 27 10:20 ftpmail. uu

Since we requested a compressedfile, we need to uncompressit before we can continue.

Renameftpmail. uu to FAQ.Zand uncompressit:
lmui@ruby 141% mv ftpmail.uu FAQ.Z
lmui@ruby 142% uncompress FAQ.Z
lmii@ruby 143% Is FAQ
FAQ

Now browse through the FAQ file at leisure.

236 X WindowSystem Administrator'sGuide

A.2.2 BITFTP

BITFTP is a mail server for BITNET users. Sendit electronic mail messagesrequesting files,
and it sendsyou back the files by electronic mail. BITFTPcurrently serves only users who
send it mail from nodes that are directly on BITNET. BITFTPis a public service of Princeton
University.

To use BITFTP,send mail containing your ftp commandsto [email protected] a complete

help file, send HELP as the messagebody. The following is the messagebody you should
send to BITFTP:

FTP export.Ics.mit.edu NETDATA

USER anonymous
PASS include here your Internet email address, NOT your BITNET address
CD /contrib
BINARY
GET FAQ.Z
QUIT

Questions about BITFTP can be directed to MAINT@PUCC on BITNET.

A.3 The xstuff Mail Archive Server

If you cannot useftp to get to a site, there may be a mail archive server that can help you. A
mail archive server is program that acceptscommandsvia e-mail. It can be used to send you
files that it has stored in its archive, or just to tell you what it has available.
MIT runs a mail archive server called xstuff that contains all the patchesfor MIT R5 and var-
ious other files. The first thing you should do is send mail to [email protected] type
"help" in the subject line. It will respond (after a while) with a full description of how to use
the program:
Subject: How to use the Xstuff server
From: Xstuff service <[email protected]>
In-Reply-To: message from [email protected] (eric pearce)
To: [email protected] (eric pearce)
Status: R

This message comes to you from the xstuff server, [email protected].

It received a message from you asking for help.

The xstuff server is a mail-response program. That means that you mail
it a request, and it mails back the response.

The xstuff server is a very dumb program. It does not have much error
checking. If you don't send it the commands that it understands,
it will just answer "I don't understand you".

Useful Things to Know 237

 As an example, if you sent mail with the subject line "send fixes 1", it will respond with
"fix-1":

From: Xstuff service <[email protected]>

Subject: fixes/1
In-Reply-To: Request from [email protected] (eric pearce) dated Tue Aug 25
13:00:01 EDT 1992
To: [email protected] (eric pearce)

Release 5 Public Patch #1

MIT X Consortium

This patch comes in two parts: this file, and the file "sunGX.uu".

The mail messagecan then be applied to the patch program to patch the X11 sourcedistribu-
tion. SeeSection 8.2.4 for a description of applying XI1 patches.
Try using the subject "index" to get a listing of available files.

A.4 Unpacking Files

The extension on the end of the file usually indicates what programs should be used for
unpacking a file.

For .Z files:

% uncompress filename.Z

For .tar.Z files:

% zcat filename.tar.Z I tar xpvf -

For files that look like this (might have .uu extension):
begin 444 mit/server/ddx/sun/sunGX.o.dist.Z
M'YVO 08$. 0!5T!OF@*@@ OD$#8!@RI( H(85.XWX!PW<"%!5X!D! J, 0

Run uudecode:

% uudecode filename

This will create the file mill server I ddxIsunlsunGX.o.dist.Z.

238 X WindowSystemAdministrator'sGuide
A.5 Making a Filesystem Available via NFS

For a host to be able to mount a remote filesystem, it will have to have an entry in the
/etc/exports file on the remote system.The format of this file has changed as NFS has gained
new functionality. The "old" style of entry in Ietc/exports is simply the name of the filesys-
tem and list of hosts that can mount it:

/usr/lib/Xll/fonts ncdl ncd2 ncd3 ncd4

The file is consulted every time a request is made to mount a filesystem.

The "new" style of entry has a different syntax with many more options. For example, the
above example would be written as:
/usr/lib/Xll/fonts -access=ncdl:ncd2:ncd3:ncd4

Under "newer" NFS, you have to execute the exportfs command after the /etc/exports file is
edited in order for the changesto take effect:
% exportfs -v /usr/lib/Xll/fonts
exported /usr/lib/Xll/fonts

To remove access to a filesystem, edit the file and run the exportfs command with the -u
option:
% exportfs -v -u /usr/lib/Xll/fonts
unexported /usr/lib/Xll/fonts

For more information, see Managing NFS and NIS by Hal Stern (O'Reilly & Associates.
1991).

A.6 How to Add a Host

A common administration task is to add a new host name to the /etc/hosts file, the Network
Information Service (NIS), or the Domain Name Service (DNS). The procedure for each of
these is described here, but they will not be adequate for more complicated configurations.
NIS is described in detail in Managing NIS and NFS by Hal Stern (O'Reilly & Associates,
1991). DNS is described in DNS and BIND by Paul Albitz and Cricket Liu (O'Reilly &
Associates, 1992). All theseexamples assumea pre-existing, working configuration.

Adding a Host to /etc/hosts

If you are not using NIS or DNS, the new host can be added directly to the file /etc/hosts,
with the IP addressfollowed by the hostname and any aliases that the host is going to be
known by:
140.186.65.13 ncd4.ora.com ncd4

Useful Thingsto Know 239

A.6.2 Adding a Host Using NIS

If you are usingNIS (previouslyknownas Yellow Pages),you first haveto determinewhich

host is the NIS master. This is usually the hostnamereturned by the ypwhich command:
% ypwhich
ruby

(This not always the case,as NIS slave serverswill also respond.)
Once you have located the master, add the new host entry to its /etc/hosts file as shown
above, and remakethe NIS map:
# vi /etc/hosts
add hostname
# cd /var/yp
# make
updated hosts

pushed hosts

You should test the map to make sure it has the new entry (in somecases,it may take a while
to propagatethe new map to all hosts within an NIS domain):
% ypmatch ruby hosts
140.186.65.13 ncd4.ora.com ncd4

If there is a problem, you will get the error:

Can't match key ncd4 in map hosts.byname. Reason: no such key in map.

A.6.3 Adding a Host Using DNS

For networks using DNS, you need to edit the configuration files for the name daemon
named, named looks at a boot file at startup, usually /'etc*'named..boot.On our name server,
this file contains the lines:

directory /var/named

; type domain source host/file backup file

primary ora.com ora.zone
primary 65.186.140.in-addr.arpa ora.revzone

The /var/named directory is where the configuration files live. The file /var/named/ora.zone
is the primary configuration file for the ora.com domain-this is the file that tells named how
to convert hostnamesto the proper IP address. The file Ivarlnamed/ora.revzone contains the
reverse entries-i.e., it tells named how to convert IP addressesto the proper hostnames
within ora.com. Note that your site will undoubtedly usedifferent pathnames.
To add ncd4 as address 140.186.65.13, we enter into /var/named/ora.zone:
ncd4 IN A 140.186.65.13
IN HINFO NCD-16 2.2.0

(The HINFO line contains host information-in this case, the version of the X server.)

240 X WindowSystemAdministrator'sGuide
Then enter into Ivarlnamedlora.revzone:

13 IN PTR ncd4.ora.com.

Using the PTR keyword, this means that host 13 in the ora.com domain (140.186.65)
resolves to hostname ncd4.ora.com.

Next, send a SIGHUP to the named daemon. This will force named to reread /etc/ named. boot
and reload the database. Most systemsmaintain a file in /etc called named.pid that contains
the process ID of named.
# kill -HUP xcat /etc /named.

If your system doesn't maintain the process ID of named,it's easy enoughto run ps and learn
it yourself.
# ps agx I grep named
88 ? S 24:48 in. named
5239 q6 S 0:00 grep named
# kill -HUP 88

Test the new entry with nslookup. To verify the hostnameto IP addressmapping:
% nslookup ncd4
Server : localhost
Address: 127.0.0.1

Name : ncd4 . ora . com

Address: 140.186.65.13

If there is a problem, it will fail with:

*** localhost can't find ncd4: Non-existent domain

To verify the IP addressto hostname mapping, set the query type to "pointer", reverse the
addressand appendthe in-addr.arpa domain:
% nslookup -q=ptr 13 .65 . 186. 140 .in-addr.arpa
Server : localhost
Address : 127 . 0 . 0 . 1

141. 65. 186. 140. in-addr.arpa name = ncd4.ora.com

If there is a problem, it will fail with:

*** localhost can't find 13 .65. 186. 140. in-addr.arpa: Non-existent domain

Useful Thingsto Know 241

A.7 Adding an Ethernet Address

When you want to boot an X terminal or diskless workstation off a server machine, you will
usually have to add its Ethernet address to the ethers database. Add the entry to the
/etc/ethers file:

00:00:a7:10:ll:bf ncd4

The letters within the hex number should be in lowercase.

If you run NIS, you will also have to remakethe ethers map on the NIS master:
# cd /var/yp
# make
updated ethers

pushed hosts

A.8 Printing Documentation in the MIT X Distribution

If you have a PostScript printer, you can print out the MIT documentation in mitlhardcopyl.
Any file with the .PSextension should print on BSD-basedUNIX machineswith:
% Ipr filename.PS

or (on System-V based machines):

$ lp filename.PS

Any filename with a .Z extension is compressed. You should uncompressit before trying to
print it:
% uncompress filename.PS.Z
% Ipr filename.PS

or:

% zcat filename.PS.Z I Ipr

If you do not have PostScriptor if you just want to look at the document on your screen,you
should use the files in the mitldocl directory.
If the file has .ms extension, this indicates that it uses the ms macro package for nroff and
troffi
% nroff -ms mit/doc/Xmu/Xmu.ms I more

If the file has a .man extension, it is meant to be installed so it can be used with the man com-
mand, but you can view it independently with:
% nroff -man mit/clients/xterm/xterm.man I more

If the file has a .tbl extension, run it through the tbl preprocessorand then through col after
passingit through nroff:
% tbl mit/doc/Server/gdz.tbl.ms I nroff -ms I col I more

242 X WindowSystemAdministrator'sGuide
 A.9 Converting a Number Into Hexadecimal and Back

Sometimesyou will have to convert a number from decimal to hex. The be program is handy
for this. Make sure all letters in the hex numbersare in uppercase.
To convert the IP address 140.186.65.13 into hex, run be:
% be

Set the output base to 16 (hex):

obase=16

Type in the numbers to be converted, separated by a semi-colon (;):

140;186;65;13
8C
BA
41
D

Type ""D" to exit be.

To use the hexadecimal value as a filename (for example, for an X terminal's remote confi-
guration file), it would be:
8CBA410D

To convert from hex to decimal, use the same procedure, but set the input base to 16 (the out-
put will default to base 10):
% be
ibase=16
8C;BA;41;D
140
186
65
13

A.10 Configuring a Sun as an X terminal

One way to breath new life into your old Sun3 hardware is to reconfigure them as X termi-
nals. A used Sun 3/50 is cheaper than most X terminals, and you get a 19" display, a nice
keyboard, an optical mouse and the ability to run the latest R5 server.
The usual way to do this is to strip down the kernel and run just the X server. A more power-
ful host on the network can run xdm and managethe 3/50 as if it were an X terminal.
The procedure for the X terminal conversion has been packagedand is available via anony-
mous ftp from several sites, the main one being ftp.ctr.columbia.edu. Check the directory
IpubiXkernel for the latest version.

Useful Things to Know 243

 There is no reason why you could not do this with other hardware. The 3/50 is singled out
only becauseit is consideredto be underpoweredby today's standards.

A.11 Using More than One Frame Buffer Under SunOS

The MIT X serverfor the Sun platform can support more than one frame buffer at a time. It is
possible to have two separatemonitors on the same host or to use separateframe buffers
within the same monitor. The cgfour frame buffer has an 8 bit color device and 1 bit mono-
chrome device. The Xsun X server will not use both unlessyou modify the default worksta-
tion configuration.
1. Become root and change directories to Idev:
% su
# cd /dev

2. Remove the default monochrome device:

# rm /dev/bwtwoO

3. Create the new monochrome device:

# MAKEDEV bwtwol

4. Make sure the kernel contains the bwtwol device and it is not commented-out. For
example, on a Sun 3/60 with a kernel named "HARRY":
# grep bwtwol /usr/sys/sun3/conf/HARRY
device bwtwol at otmem 7 csr Oxff300000 priority 4# 3/60
device bwtwol at otmem 7 csr Oxff400000# 3/60

If the device is missing, add it to the kernel config file and build a new kernel.

If this procedure works, you should be able to toggle back and forth between the frame buf-
fers just by moving the mousepointer to the edge of the display.
Some systemscan support more than one physical monitor. The Sun color IPC comes with a
monochrome frame buffer built onto the CPU board and a cgthree card in one of the Sbus
slots. If you connect a monochrome monitor to a CPU and a color monitor to the cgthree
device, you can run the X server on both. Moving the mouse pointer to edge of the screen
will move it onto the adjacentmonitor.

244 x WindowSystemAdministrator'sGuide
 B

Compiling Public Domain Software

Public domain software for X is available all over the Internet, but you may
not think you have the right programming skills, or no one ever explicitly told
you what to do. This appendix is a tutorial on how to find and compile public
domain software.

In This Appendix:
Finding the Sources 247
Using an Archie Server 248
Get the FAQ 250
The Usual Suspects 250
An Example: xarchie 251
Getting the xarchie Sources 251
Untarring the Sources 252
Editing the Imakefile 254
Compiling the Source 255
Using Patches 259
Another Example: xkeycaps 264
Related Documentation . .. 268
 B
Compiling Public Domain Software

You've probably seen this sort of talk over the newsgroups: "Does anyone know where I can
get xtetris?" "Is there an ftp site for xpostit?" You know that one of the best things about X is
that there's all this great public domain software available, but you're not sure how to go
about getting it. Either you don't know how to ftp the sources,or you don't know how to use
imake or make, or you aren't much of a C programmer so the whole idea of dealing with the
sourcejust scaresyou.
Well, the good news is that for most sourcedistributions, you don't needto know very much
about make or imake, and you don't really need to know much about programming in
C-mostly all you need to know is how to follow directions. This appendix gives you some
idea of how to compile sources without knowing a lot about what you're doing. If you've
been installing X from source or if you're a competent (and confident) C programmer in your
own right, then you already know all the material in this appendix and it isn't for you. But if
you're one of thesepeople who's Scared of the Source, then this appendix may help.
Don't expect to learn much about make or imake in this appendix, just enough to get through
some of the simpler builds. If you're interested only in how to compile the XI1 sources
themselves,see Chapter 8. But if you already have XI1 installed and you just want to install
new software, read on.

B.1 Finding the Sources

There are a lot of ways to find out about a program. You might see a reference to it on a
newsgroup, or you might see it running on someoneelse's machine, or you might have read
about it in this book. Let's supposeyou saw a posting on the net about the xrolodex client:
From: [email protected]
Newsgroups: comp. windows. x. apps
Subj ect: xrolodex

Hey,

Has anyone seen the new xrolodex app? How is it related to

xrolo?

-Ross

Compiling Public Domain Software 247

 When you read this message,you are intrigued by the possibilities of a rolodex program, and
you wonder whether it's available at no cost.

B.1.1 Using an Archie Server

The first thing to try is to use an Archie server. Archie is a robust databaseof anonymousftp
sites and their contents. If you have Internet access,the most direct way to gain accessto
archie is to telnet directly to one of the Archie servers. Current Archie servers are listed in
Table B-l.

Table 6-7. Archie Servers as of January 3, 1992

Site IP Address Location

archie.mcgill. ca 132.206.2.3 McGill University, Montreal, Canada

archie.sura.net 128.167.254.179 SURAnet, College Park, Maryland, USA
archie.ans.net 147.225.1.2 ANS, New York, USA
archie.unl.edu 129.93.1.14 Lincoln, Nebraska, USA
arch ie .rutgers. edu 128.6.18.15 Piscataway, New Jersey, USA

archie.funet.fi 128.214.6.100 FUnet, Helsinki, Finland

archie.au 139.130.4.6 Deakin University, Geelong, Australia
archie.doc.ic.ac.uk 146.169.11.3 Imperial College, London, UK
cs.huji.ac.il 132.65.6.5 Hebrew University, Jerusalem,Israel

In our case, since Archie was written by the Archive Group at McGill University, it seemed
fitting to use the one at McGill. In reality, you should use the server closest to you, since the
McGill machine is generally overloaded with requests.
You should generally use a front-end Archie client program to accessan Archie server, such
as archie or xarchie (we show how to build xarchie later in this chapter, in Section B.2). But
you can also connect to Archie directly using telnet.
linui@opal% telnet archie.mcgill.ca
Trying 132.206.2.3 ...
Connected to quiche.cs.McGill.CA.
Escape character is 1A] '.

SunOS UNIX (quiche.CS.McGill.CA)

login:

Log on as archie. (There is no password.)

login: archie
ARCHIE: The McGill School of Conputer Science Archive Server [2 Apr 1992]

Use the 'servers' command to list all archie servers.

A limit of 10 concurrent telnet sessions has been put on archie.mcgill.ca.

248 The X WindowSystemAdministrator'sGuide

 Alternative access through the standalone clients available via
anonymous ftp to this machine. See README file in -archie/clients.

** 'help' for help

** corrections/additions to [email protected]
** bug reports, comments etc. to eirchie-19archie.mcgill.ca

archie>

For a full listing of commands,type help.

As an example of how to use archie to find a program called xrolodex, type:
archie> prog xrolodex

The first thing Archie does is find how many matchesto xrolodex there are in the database.It
keeps you updated on how many matches it's found so far, and how far it's gotten in its
search.

# matches / % database searched: 1/78%

When it is 100% through the database,the list of sites that have xrolodex will stream to your
terminal. For the purposes of this example, we have deliberately chosen a recently-
announced program that has not made it to many sites yet (at least, not at the time of this
example). If we had searchedfor something like xpostit, many screenfuls of output would
have been reported.
archie> prog xrolodex
# matches / % database searched: 4 / 100%
Host think.com (131.239.2.1)
Last updated 05:54 25 Feb 1992

Locat i on: /think

FILE rw-rw-r- 53208 Dec 4 1990 xrolodex.shar.Z

Host citi.umich.edu (141.211.128.16)

Last updated 16:05 9 Apr 1992

Location: /afs/alw.nih.gov/dcrt/brunetti/01dfiles
DIRECTORY rwxrwxrwx 2048 Apr 1 10:16 xrolodex
Location: /afs/alw.nih.gov/dcrt/brunetti
DIRECTORY rwxrwxrwx 2048 Apr 1 10:16 xrolodex

Host plaza.aarnet.edu.au (139.130.4.6)

Last updated 05:54 27 Apr 1992

Location: /Xll/contrib
FILE r-r~r- 103267 Apr 24 02:28 xrolodex.tar.Z

archie>

In this example, the pattern used for the prog command is assumedto be an exact match to
the name of the program we want. You can specify different ways of searchingusing the set
search command.For example:
archie> set search sub
archie> prog rolo

will force a searchof all items in the databasewith "rolo" as a substring.

Compiling Public Domain Software 249

 Rather than using telnet to directly contact an Archie server, there are programsavailable to
automate the search. See Section B.2 for information on obtaining and compiling xarchie,
which provides an XI1 interface to accessingan Archie server.
If you don't have Internet accessat all, you can use the e-mail interface by sending mail to
archie@/zos/, where host is one of the machines listed in Table B-l. See The Whole Internet
User's Guide & Catalog by Ed Krol (O'Reilly & Associates, 1992)for more information.

B.1.2 Get the FAQ

Archie is a great way to find sources. However, if you have accessto the comp.windows.x
FAQ (Frequently Asked Questions) list, looking through the FAQ might actually be easier.
The FAQ is a great wealth of information that is posted at the beginning of each month to the
newsgroup comp.windows.x. It is updated frequently, so if you have absolutely any question
about X, the first place you should look is in the FAQ.
As far as sources are concerned, some public domain sources are placed on several anony-
mousftp sites, but not all are updated when new versions or bug fixes are announced.If the
comp.windows.xFAQ list tells you where to get sources,it's likely to tell you the most reli-
able site.

If you don't have a FAQ handy, either post to one of the comp.windowsJCnewsgroups for
someoneto send it to you, or ftp it yourself as described in Section A.2. You can also get it
from [email protected]. Or if you can wait a little, look for it on comp.win-
dows.x-the FAQ is promptly re-postedat the beginning of every month, as are the FAQs for
comp.windows.x.motif and comp.windows.openlook.
(If you don't have accessto Usenet, you can get on a mailing list called xpert. To get on that
mailing list, send mail to [email protected].)

At this writing, there are 145 questions answeredin the FAQ, definitely worth the bandwidth
to get it. If you find it useful, also look for the FAQs for OSF/Motif and for OPEN LOOK.

B.1.3 The Usual Suspects

You can find a description of other ways to find sourceson the machine rtfm.mit.edu, in the
directory Ipublusenetlnews.answers. A list of ftp sites can be found in the ftp-list directory,
and the Hie finding-sourcesgives somemore information on how to find what you want.
If neither the FAQ nor Archie mentions what you want, and you have Internet access,try a
few of the usual suspects-such as export.lcs.mit.edu (where you'd also find the XI1 sources
themselves)in the Icontrib directory, orftp.uu.net in the I comp.windows.x directory.
(While you're at export or uunet, you might want to browse around a bit. There's a lot of
good stuff available, you just needto know about it.)

If all else fails, try sending a polite post to comp.windows.xasking if this program is public
domain and, if so, would anyone be kind enough to help you get it.

250 The X WindowSystemAdministrator'sGuide

 B.2 An Example: xarchie

If you're interested in trying out a lot of public domain software, it's a good idea to get xar-
chie to help you find things. For that reason,we use xarchie for our first example.
We are running SunOS4. Lv under MIT XI1R5, and xarchie 1.3 builds cleanly for us. If you
have trouble building xarchie on your platform, look for xarchie 2.0, which should be avail-
able by the time this book goes to press. Among other things, the new version of xarchie has
a cleaner /makefile, solving some build issueson OpenWindows and on SGI machines.

B.2.1 Getting the xarchie Sources

xarchie isn't listed in the FAQ, but we know via an earlier Archie query (which we spared
you in this appendix) that it can be found on hundreds of archives. One of those archives is
export.lcs.mit.edu. We ftp to export, log in as anonymous, and go directly to the contribl
directory.
lmui@opal% ftp export.lcs.mit.edu
Connected to export.lcs.mit.edu.
220 export.lcs.mit.edu FTP server (NEWS-OS Release 4.1C) ready.
Name (export.lcs.mit.edu:lmui) : anonymous
331 Guest login ok, send ident as password.
Password:
230 Guest login ok, access restrictions apply.
ftp> cd contrib
250 CWD command successful.
ftp>

There, we look for anything resembling the name "archie." Not all ftp servers accept wild-
cards, but this one does.

ftp> Is *rchie*
200 PORT command successful.
150 Opening data connection for /bin/Is (ascii mode) (0 bytes).
xarchie-1.3.tar.Z
226 Transfer complete.
remote: *rchie*
19 bytes received in 0.015 seconds (1.2 Kbytes/s)
ftp>

The compressedtar file xarchie-1.3.tar.Z seemsto be what we want. We set ourselves up for
binary transfer,get the file, and then quit out of ftp.
ftp> bin
200 Type set to I.
ftp> get xarchie-1.3.tar.Z
200 PORT command successful.
150 Opening data connection for xarchie-1.3.tar.Z (binary mode)
(179119 bytes).
226 Transfer complete.
local: xarchie-1.3.tar.Z remote: xarchie-1.3.tar.Z
179119 bytes received in 46 seconds (3.8 Kbytes/s)

Compiling Public Domain Software 251

 ftp> quit
221 Goodbye.
lmui@opal%

B.2.2 Untarring the Sources

Once we have the file on our system, it's a good idea to seewhat it contains before we untar
it. Use the zcat command to uncompressthe file to standardoutput and pipe that to tar tf-lo
see what files the tar archive contains.

lraui@opal% zcat x* I tar tf -

Ad2c/Imakefile
Ad2c/Makefile
Ad2c/README
Ad2c/ad2c.man
Ad2c/ad2c.script
EzMenu/EzME.C
EzMenu/EzME.h
EzMenu/EzMEP.h
EzMenu/EzMenu.c
EzMenu/EzMenu.h
EzMenu/EzMenuP.h
EzMenu/Imakefile
EzMenu/Makefile
EzMenu/README
EzMenu/ezMenu .man
Imakefile
MANIFEST

Since we don't want to clutter the current directory with all these files, create a new xarchie
subdirectory and move the compressedtar file into that directory.
lmui@opal% mkdir xarchie
lmui@opal% mv xarchie-1. 3 .tar. Z xarchie/

Change directory to the xarchie directory and then untar the file for real. Use the p option to
tar so you retain permissions.When it is done, list the contentsof the directory.
lmui@opal% cd xarchie
lmui@opal% zcat *. Z I tar xfp -
lmii@opal% IB -aF
./ classnames.c pprot.h
../ classnames.h procquery.c
Ad2c/ confirm.c procquery.h
EzMenu/ confirm.h ptalloc.c
Imakefile copyright.h rdgram.h
MANIFEST db. c regex.c
Makefile db.h regex.h
README dialog.c settings.c
README.FILES dialog.h settings.h
README.PROSP dirsend.c stcopy.c
TODO ftp.c support.c
Xarchie.ad ftp.h types.c
Xarchie.ad. h get_pauth.c types.h

252 The X WindowSystemAdministrator'sGuide

 act ions.c get_vdir.c udp.c
actions.h patchlevel.h vl_comp.c
alert.c pauthent.h vlalloc.c
alert.h pconpat.h xarchie-1.3.tar.Z
appres.h perrmesg.c xarchie.c
aquery.c perrno.h xarchie.h
archie.h pfs.h xarchie.man
atalloc.c pmachine.h
lmui@opal%

Now we've come to the First Cardinal Rule of compiling sources: when there's a README,
read it.

lmui@opal% more README

README for Xarchie - XI1 browser interface to Archie

George Ferguson, [email protected]

Last Change: 12 Nov 1991

DISCLAIMER:

This is release 1.3 of xarchie - an X browser interface to

the Archie Internet information system.

This software is provided as is with no warranty expressed or

implied. I hope you find it useful, but I won't be held responsible
for any damage that may occur from reading, compiling, installing,
using, or even thinking about it.

Further down in the READMEare the instructions on how to actually install the program.
INSTALLATION:

1. Edit the Imakefile to reflect any changes for your site. These
include setting BINDIR, LIBDIR, and MANDIR if needed, and
checking CDEBUGFLAGS if debugging or optimization is desired.

If your system doesn't have re_comp() and re_exec(), then you

need to uncomment the appropriate section in the Imakefile to
include those routines.

Compiling this program requires the "ad2cn program. You should

have received a copy of ad2c with this distribution, in the
subdirectory "Ad2c". You should set the AD2C variable as
required. Actually, ad2c is only required if you change Xarchie.ad
and want the new defaults compiled in as fallback resources. If
you don't have ad2c, you probably want to remove the line that
adds Xarchie.ad.h to the "clean" target.

You may want to change defaults in Xarchie.ad; consult the manpage

for details, and see above about ad2c.

This brings us to Cardinal Rule Number 2: follow directions.

Compiling Public Domain Software 253

B.2.3 Editing the (makefile

You may not feel up to editing an Imakefile, but we recommendthat you give it a try regard-
less. The xarchie Imakefile is somewhat non-standard,but it is straightforward and well-doc-
umented, so it's a good place to start becoming familiar with imake. We'll build a more stan-
dard program,xkeycaps,later in this appendix.
If you don't know what imake is, it's basically a utility to create Makefiles based on system
dependencies.It actually makes a lot of sense-if you're building a lot of applications for a
lot of different machines,you end up editing your Makefile a lot according to each different
machine, and then you have to edit the Makefile of the next application according to the same
dependencies,and it seemsas if you keep duplicating your edits, imake lets you set up sys-
tem dependencies in an independent place, in a file called Imake.tmpl, usually kept in
lusrlliblXlllconfig. For more information on imake syntax, seeSection 8.7.
If you just read the Imakefile carefully, you'll get the idea of the sorts of things you might
change.
#
# Imakefile for xarchie : Xll Browser interface to Archie
#
# George Ferguson, [email protected], 12 Sep 1991.
#

# Where do you want this stuff? Uhcomment and adjust these to change the
# destinations of "make install" and "make install.man" if the defaults
# are not satisfactory.
#BINDIR = bin
#LIBDIR = lib
#MANDIR = man/manl
##undef ManSuffix
##define ManSuffix 1

BINDIR is the target directory where the xarchie program will eventually be installed. If you
prefer that xarchie be installed in I usrIlocal/bin, this is where you'd specify it. Otherwise,
the program will be installed in whatever directory imake has been configured for on your
system. On our system, the default is lusr/bin/Xl 1.

LIBDIR is your X library directory. On our system, the default is lusrlliblXl 1. MANDIR is
where the manual pagesgo. On our system,the default is lusr/man.
In all three cases,we are satisfied with the default values and leave them unchanged. Con-
tinue with the Imakefile:
# Where is the app-defaults to C converter?
# Only needed if you change the app-defaults file Xarchie.ad and want the
# changes compiled into the program. If you don't have ad2c you should
# remove the extra clean target for Xarchie.ad.h below. If you lose
# Xarchie.ad.h and can't remake it, create it to be an empty file. Of course
# then you'll have to use the resource file at run time.
# If your ad2c came from this xarchie distribution, then use the following
# target, otherwise change it to reflect where you put ad2c.
AD2C = Ad2c/ad2c.script

# Where is the EzMenu widget package?

# You should have received a copy of the EzMenu package with this

254 The X WindowSystemAdministrator'sGuide

 # xarchie distribution.
EZMENUDIR = EzMenu
EZMENULIB = ezMenu$(TARGETJ^ACH)

Since both the ad2c and EzMenu packageswere included in the tar file, we don't have to do
anything here.
# How excited are you about debugging? This can be -g, -O, or nothing.
CDEBUGFLAGS = -g

# To enable Prospero tracing (controlled by the -debug option), uncomment

# this
#PDEBUG = -DDEBUG

# Does your system have re_comp() and re_exec(), or regcmp() and regex()
# [in the case of A/UK]1 If not, uncomment the following definitions.
#REGEXC = regex.c
#REGEXO = regex.o

#ff##f#####f##t######t####ft##########f######f####f###f#f#t#########f##f#i#
# Nothing to change below here...

We don't care about debugging, we don't know what Prospero tracing is, and we've deter-
mined that we have the re_comp() and re_exec() functions by using the man command on
them.

We thus declare ourselvesto have finished editing the Imakefile.

As for editing the application defaults: the file Xarchie.ad is the systemwideresource file for
the xarchie application. It's worth it to take a minute to make sure it's set up the way you
want it.

Xarchie.ad : Application defaults for the Xll browser interface to Archie

George Ferguson, [email protected], 12 Nov 1991.

Non-widget resources
Xarchie.archieHost: archie.sura.net

! Possible values are: exact, substr, subcase, or regexp

Xarchie.searchType: exact

This is when you'd change the name of the archie host to the one closest to you. For example,
you might changeit to the one at Rutgers:
Xarchie.archieHost: archie.rutgers.edu

B.2.4 Compiling the Source

Once the Imakefile is set up, compiling is usually a matter of just executing a few commands
and hoping it works. From the README:
2. Execute
% xmkmf
to create the Makefile.

Compiling Public Domain Software 255

If you're running X11R4 or later, your X distribution comes with a command called xmkmf,
which stands for "X Make Makefile." xmkmfis a shell script (usually kept in lusrIbinlXll)
that is designed to run imake to create Makefiles for third-party XI1 software distributions.
See Section 8.6.1 for more information on xmkmf.

If a software distribution comes with a proper Imakefile, if your X distribution is setup prop-
erly, and if you're generally a lucky person, you can simply run xmkmf and your Makefile(s)
are all set.

lmui@opal% xmkmf
mv Makefile Makefile.bak
imake -DUselnstalled -I/usr/lib/Xll/config
lniui@opal%

You now have a new Makefile. (Although a Makefile was supplied with the distribution for
sites that may not have imake, it's always better to use one generatedby imake.)
3. Execute
% make Makefiles
to run xmkmf in the Ad2c and EzMenu subdirectories. Alternately,
run it (or imake) in each subdirectory by hand.

4. Execute
% make depend
to add the dependencies to the Makefile. This is necessary to
ensure that Xarchie.ad.h is created when needed.
IMPORTANT: Ignore the error message from makedepend if Xarchie.ad.h
is not found; it will be created automatically.

Once again, follow directions.

lmui@opal% make Makefiles
making Makefiles in ./Ad2c...
rm -f Ad2c/Makefile.bak
+ mv Ad2c/Makefile Ad2c/Makefile.bak
cd Ad2c; imake -DUselnstalled -I/usr/lib/Xll/config -DTOPDIR=../. -DCURD
IR=./Ad2c; \
make Makefiles
making Makefiles in ./EzMenu...
rm -f EzMenu/Makefile.bak
+ mv EzMenu/Makefile EzMenu/Makefile.bak
cd EzMenu; imake -DUselnstalled -I/usr/lib/Xll/config -DTOPDIR=../. -DCU
RDIR=./EzMenu; \
make Makefiles
lmui@opal% make depend
makedepend -s "# DO NOT DELETE" - -I. -lEzMenu -DARCHIE
-DXARCHIE - aquery.c atalloc.c dirsend.c get_pauth.c get_vdir.c
perrmesg.c ptalloc.c stcopy.c support.c vl_comp.c vlalloc.c xarchie.c
db.c actions.c types.c classnames.c procquery.c settings.c ftp.c
alert.c confirm.c dialog.c

(In R5, xmkmf-a will take combine steps2-4 of this example.)

Now you're ready for the moment of truth:
5. Make the package using
% make
or install it directly with
% make install install.man

256 The X WindowSystem Administrator'sGuide

 Note that this will also "make install" in Ad2c and EzMenu by
default. Since you may want to install xarchie without installing
these other things, you can instead do
% make install.xarchie
to install xarchie, its resource file, and its manpage only.

We don't recommend installing things until you know what you're installing and where it's
going to go. So make the program separately:
lmui@opal% make
making all in ./Ad2c...
ad2c is up to date
making all in ./EzMenu...
cc -g -I/usr/staff/include -target sun4 -c EzMenu.c
cc -g -I/usr/staff/include -target sun4 -c EzME.c
rm -f libezMenu-sparc.a
ar cq libezMenu-sparc.a EzMenu.o EzME.o
ranlib libezMenu-sparc.a
cc -g -pipe -I. -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c aquery.c
cc -g -pipe -I. -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c atalloc.c
cc -g -pipe -I. -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c dirsend.c
cc -g -pipe -I. -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c get_pauth.c
cc -g -pipe -I. -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c get_vdir.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c perrmesg.c
cc -g -pipe -I --LtLzraenu
TT-,-,, -UAKunj-d -DXARCHIE
-DARCHIE -JJAAKUHJ.^ -target sunft
sun4 -c ptai-LOC.
ptalloc.
cc -g -pipe -I. -lEzMenu -DARCHIE -T"YyaT?n-n"R
-nARPHTTT
uni\v_~ii-Liii -DXARCHIE
i^^\rxr\.v_jrixj^ -1-arrrot-
-target
L.aa_ycL- sun4
Gin-id
DUII^I -c\-
-f stcopy.c .^r
ct-r-m-n/
ou^w^/y
cc -g -pipe -I -lEzMenu
-xi^'ieiiu -DARCHIE -DXARCHIE -target -taraet sun4 -c suDDort.
support.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c vl_comp.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c vlalloc.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c xarchie.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c db.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c actions.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c types.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c classnames.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c procquery.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c settings.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c ftp.c
cc -g -pipe -I -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c alert.c
cc -g -pipe -I. -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c confir
confirm.c
cc -g -pipe -I. -lEzMenu -DARCHIE -DXARCHIE -target sun4 -c dialog.
(cd EzMenu; echo "making all in ./EzMenu..."; \
make 'CDEBUGFLAGS=-g' all);
making all in ./EzMenu...
rm -f xarchie
cc -o xarchie aquery.o atalloc.o dirsend.o get_pauth.o get_vdir.o
perrmesg.o ptalloc.o stcopy.o support.o vl_comp.o vlalloc.o xarchie
db.o actions.o types.o classnames.o procquery.o settings.o ftp.o
alert.o confirm.o dialog.o -g -pipe -LEzMenu -lezMenu-sparc -iXaw
-iXmu -iXt -iXext -1X11
lmui@opal%

And now, believe it or not, the xarchie program is done.*

lmui@opal% Is -F xarchie
xarchie*

*If you get a compilation error, it's probably because of missing header files or function definitions. See Section
8.8.1 for more information on what to do in this situation.

Compiling Public Domain Software 257

We like to try out a program before we install it and its application defaults. Copy the Xar-
chie.ad file to Xarchie, and set your XAPPLRESDIRenvironment variable to the current direc-
tory so that the application will find the resourcefile. Or just set your XENVIRONMENTenvi-
ronment variable to Xarchie.ad. Then start up the application.
lmui@opal% setenv XENVIRONMENT Xarchie.ad
lmui@opal% . /xarchie &

You should seesomething like the window shown in Figure B-l.

| Quit 11
Querij| i >4;o:"
i, j Save| |Ftp| | SearchType11
Sort Type11
Nice Level11
Settings^
Status: Found 10 matches - Ready

citi.umich.edu
P1aza.aarnet.edu.au
scsluiide.sony.co.jp
src.doc.ic.ac.uk
.urz.uni-heidelberg

toklab.ics.osaka-u.ac.ji
uts.mcc.ac.uk
xll.informatik.uni-dort

Search Term; xrolodex

think .com

Location:n: /think

File: xrolodex.shar.Z

Size: 53208 Mode:|-rui-rurr- Date: Dec 4 1990

Figure B-1. xarchie window

In the example figure, you see that once xarchie has located the utility you want, you can
automatically ftp it by selecting a site and pressingthe ftp button.
Play with xarchie a bit. When you're happy with it, install it. Before you do that, it's a good
idea to do make -n install first to see where make intends to install the xarchie program.
(The -n option to make says not to actually execute these commandsbut just tell you what it
would do. It's a good idea since you should never trust that you won't end up blowing away
some system files.)

We're choosing to install the xarchie program, manpage,and application defaults only-we
aren't installing the other packagesthat came with xarchie. (The xarchie build is unusual in
that it installs the manual page as it installs the application itself. Most builds usually require
you to run a separatemake install.man to install the manual page for the application.)
lmii@opal% make -n install.xarchie
(cd EzMenu; echo "making all in ./EzMenu..."; \
make -n 'CDEBUGFLAGS=-g' all);
making all in ./EzMenu...
rm -f xarchie

258 The X WindowSystemAdministrator'sGuide

 cc -o xarchie aquery.o atalloc.o dirsend.o get_pauth.o get_vdir.o
perrmesg.o ptalloc.o stcopy.o support.© vl_comp.o vlalloc.o xarchie.o
db.o actions.o types.o classnames.o procquery.o settings.o ftp.o
alert.o confirm.o dialog.o -g -pipe -LEzMenu -lezMenu-sparc -iXaw
-iXmu -iXt -iXext -1X11
install -c -s xarchie /usr/bin/Xll
install -c -m 0444 Xarchie.ad /usr/lib/Xll/app-defaults/Xarchie
install -c -m 0444 xarchie.man /usr/man/mann/xarchie.1

If you're satisfied with these locations, run the installation for real. (You may have to become
root now.)
lmui@opal% su
Password:
cpal# make install
making all in ./EzMenu...
rm -f xarchie
cc -o xarchie aquery.o atalloc.o dirsend.o get_pauth.o get_vdir.o
perrmesg.o ptalloc.o stcopy.o support.o vl_comp.o vlalloc.o xarchie.o
db.o actions.o types.o classnames.o procquery.o settings.o ftp.o
alert.o confirm.o dialog.o -g -pipe -LEzMenu -lezMenu-spare -IXaw
-IXmu -IXt -IXext -1X11
install -c -s xarchie /usr/bin/Xll
install -c -m 0444 Xarchie.ad /usr/lib/Xll/app-defaults/Xarchie
install -c -m 0444 xarchie.man /usr/man/mann/xarchie.1

And now it's just a matter of running rehash and starting the xarchie application.
lmui@opal% rehash
lmui@opal% xarchie &

Note that, for this example, you didn't need to know any C programming, you just neededto
use some basic common sense.Not all compilations work this easily, but many do.

B.3 Using Patches

A patch to a program is exactly what it soundslike: a fix to build on the current sources. As
an example, in the following example we have the xwebster sourcesfrom export.lcs.mit.edu,
which we will unpack and untar.
lmui@opal% zcat xwebster.tar.Z I tar xfp -
lmui@opal% cd xwebster
lmui@opal% Is -F
Imakefile controlpanel.c user_prefs.h xwebster.c xwebster.xbm
Makefile display_def.c wordlist.c xwebster.h
Xwebster.ad patches/ xwebster.REAEME xwebster.man

(The xwebster program is a client program dependingon accessto a licensed Webster server.
Unless you have accessto such a server, you will not be able to use this program. It also
requires a compiled Xw library, which many vendors don't include-you'll have to build it
yourself.)

CompilingPublic DomainSoftware 259

Note the patches! subdirectory: within that directory you find three patch files:
lmui@opal% Is patches
patch-00 patch-01 patch-02

All patchesshould be applied in order.

The patch program is available in the mitlutillpatch directory in the XI1 sourcedistribution.
The best way to recognize a patch file is by lines starting with asterisks (*), dashes(-), hash
signs (#), plus signs (+), and exclamation points (!). When you look at the file
patches!patch-00, you'll seethat it reads:
Replied: Wed, 28 Feb 90 16:04:12 PST

Received: by church.csri.toronto.edu id 1012; Tue, 20 Feb 90 02:20:02

EST
From: Mark Moraes <[email protected]>
To: [email protected]
Subject: R4 xwebster fix
Cc: [email protected]
Message-Id: <[email protected]>
Date: Tue, 20 Feb 90 02:19:47 EST

xrdb doesn't seem to like comments in defaults files starting with #.

(Possibly a bug in Hence this fix. I also fixed the Xw widgets to
stop Xt whining every time xwebster tries to change the titlebar. (see
fixes on expo) (It doesn't matter when Xwebster.ad is installed in
LIBDIR/app-defaults, but since I test the program by xrdb'ing the
app-defaults file and then running the program, it didn't work then)

*** #Xwebster.ad~ Mon Feb 19 23:57:14 1990

- Xwebster.ad Mon Feb 19 23:57:14 1990

*** 1 3 ****
- 1,4
+ /*
########################################################################
##
#
# File: Xwebster

*** 31,36 ****

- 32,38
##
## this is the help display that comes up initially when you run Xwebster.
##

To apply the patch file, do:

lmii@opal% patch < patches/patch-00
Hmm... Looks like a new-style context diff to me...
The text leading up to this was:

*** #Xwebster.ad~ Mon Feb 19 23:57:14 1990

- Xwebster.ad Mon Feb 19 23:57:14 1990

Patching file Xwebster.ad using Plan A...

Hunk #1 succeeded at 1.

260 The X WindowSystem Administrator'sGuide

 Hunk #2 succeeded at 32.
Hunk #3 succeeded at 57.
Hunk #4 succeeded at 71.
Hunk #5 succeeded at 105.
Hunk #6 succeeded at 116.
Hunk #7 succeeded at 131.
Hunk #8 succeeded at 166.
Hunk #9 succeeded at 173.
Hunk #10 succeeded at 199.
Hunk #11 succeeded at 259.
Hunk #12 succeeded at 271.
Hunk #13 succeeded at 287.
Hunk #14 succeeded at 319.
Hunk #15 succeeded at 332.
Hunk #16 succeeded at 342.
Hunk #17 succeeded at 372.
Hunk #18 succeeded at 386.
Hunk #19 succeeded at 411.
done

(The messagestarting with "Hmm ... "is the patch program's polite way of telling you
what it thinks it's doing.)

The secondpatch (patcheslpatch-01)resemblesthe first in form:

Return-Path: [email protected]

Received: from localhost.ARPA by gauss.llnl.gov (4.0/1.15)

id AA00823; Tue, 3 Apr 90 13:11:46 PDT
Message-Id: <[email protected]>
From: [email protected] (Casey Leedom)
To: [email protected] (Niels P. Mayer)
Subject: Small fixes.to X.VllR4/contrib/clients/xwebster/Imakefile
Date: Tue, 03 Apr 90 13:11:45 -0700
Sender: [email protected]

*** Imakefile-dist Mon Mar 6 03:41:36 1989

- Imakefile Wed Mar 28 11:00:54 1990

*** 1 37 ****
#
# This assumes that the HP Xwidget sources patched for r3 have been placed
! # in $(TOP)/lib/Xw.
#
! XWLIB = $(TOP)/lib/Xw/libXw.a

Apply this patch in a similar fashion:

lmui@opal% patch < patches/patch-01

Hmm... Looks like a new-style context diff to me...
The text leading up to this was:

*** Imakefile-dist Mon Mar 6 03:41:36 1989

-- Imakefile Wed Mar 28 11:00:54 1990

Patching file Imakefile using Plan A...

Hunk #1 succeeded at 1.
done

Compiling Public Domain Software 261

The third patch file looks different.
Fran [email protected] Wed Jun 28 15:13:32 1989
To: [email protected]
Subject: New xwebster features
Reply-To: Sam Horrocks <[email protected]>
Date: Wed, 28 Jun 89 15:08:45 -0700
Message-Id: <[email protected]>
From: Sam Horrocks <[email protected]>

I've added a couple of new features to xwebster and I'm sending you the
patches. I've added a button to do spelling of the word (alternate spellings
appear in the upper window) and I've added a toggle to put xwebster into
thesaurus mode. Here are the diffs:

: Remove anything above this line.

: This is a shar archieve. Extract with sh, not csh.
: The rest of this file will extract:
: xwebster.diffs
echo extracting - xwebster.diffs
sed 's/AX//' > xwebster.diffs « '/*EOF'
X*** /tmp/,RCStlall790 Wed Jun 28 14:27:31 1989
X xwebster.man Wed Jun 28 14:22:32 1989

This file is a shar file. Edit out the mail header and extract the patch file with sh or (prefer-
ably) use the unshar command. (If you use unshar, you don't have to edit out the mail
header.)Do not unpack the shar file as root.
lmui@opal% unshar patches/patch-02
unshar: Sending header to patch-02.hdr.
unshar: Doing patches/patch-02:
extracting - xwebster.diffs

The resulting xwebster.diffs file contains:

*** /tmp/,RCStla!1790 Wed Jun 28 14:27:31 1989
xwebster.man Wed Jun 28 14:22:32 1989

*** 50,55 ****

- 50,65
attempt to complete the word. If the word can be completed, the new word
is placed in the TextEdit widget; otherwise, the program beeps and
displays a message indicating that the word is ambiguous.
+ .PP
+ Typing \fB'.'\fP or mousing \fB[Spell]\fP causes the program to look up
+ alternate ways to spell what you just typed. The list of spellings will
+ be displayed in the browser panel.

Run the patch command to complete the patches:

lmui@opal% patch < xwebster.diffs
Hmm... Looks like a new-style context diff to me...
The text leading up to this was:

*** /tmp/,RCStla!1790 Wed Jun 28 14:27:31 1989

I xwebster.man Wed Jun 28 14:22:32 1989

Patching file xwebster.man using Plan A...

262 The X WindowSystemAdministrator'sGuide

 Hunk #1 succeeded at 50.
Hmm... The next patch looks like a new-style context diff to me.
The text leading up to this was:

*** /tmp/,RCStlall804 Wed Jun 28 14:29:00 1989

-- Xwebster.ad Wed Jun 28 14:22:26 1989

Patching file Xwebster.ad using Plan A...

Hunk #1 succeeded at 48 (offset 2 lines).
Hunk #2 succeeded at 307 with fuzz 1 (offset 28 lines).
Hunk #3 succeeded at 297 (offset 4 lines).
Hunk #4 failed at 368.
Hunk #5 succeeded at 454 (offset 49 lines).
1 out of 5 hunks failed-saving rejects to Xwebster.ad.rej
Hmm... The next patch looks like a new-style context diff to me.
The text leading up to this was:

*** /tmp/,RCStla!1812 Wed Jun 28 14:30:18 1989

controlpanel.c Wed Jun 28 14:22:27 1989

Patching file controlpanel.c using Plan A...

Hunk #1 succeeded at 40.
Hunk #2 succeeded at 47.
Hunk #3 succeeded at 209.
Hunk #4 succeeded at 270.
Hunk #5 succeeded at 330.
Hunk #6 succeeded at 374.
Hunk #7 succeeded at 402.
Hunk #8 succeeded at 426.
Hunk #9 succeeded at 483.
Hunk #10 succeeded at 502.
Hunk #11 succeeded at 520.
Hmm... The next patch looks like a new-style context diff to me.
The text leading up to this was:

*** /tmp/,RCStla!1826 Wed Jun 28 14:32:56 1989

xwebster.c Wed Jun 28 14:22:31 1989

Patching file xwebster.c using Plan A...

Hunk #1 succeeded at 266.
Hunk #2 succeeded at 275.
done

The error you may want to pay attention to is the one that failed, at line 368 in the Xweb-
ster.ad file. The patch program is nice enough to tell you what failed and to savethe rejected
patch in a file called Xwebster.ad.rej. (You can use the -s option to patch to suppresscom-
ments and report failures only.) You can examine that file and see if you can reconstruct
what it intends to do, but that's beyond the scopeof this exercise.

When you are satisfied that all patchesare applied, you can complete the build:
lmui@opal% xmkmf
mv Makefile Makefile.bak
imake -DUselnstalled -I/usr/lib/Xll/config
lmui@opal% make depend
makedepend -s "# DO NOT DELETE" - -I/work/lmui/src/Xw
-DAPPDEFAULTSDIR=
display_def.c wordlist.c xwebster.c

CompilingPublic DomainSoftware 263

 lmui@opal% make
cc -0 -pipe -I/work/lmui/src/Xw -DAPPDEFAULTSDIR=
-target sun4 -c controlpanel.c
cc -O -pipe -I/work/lraui/src/Xw -DAPPDEFAULTSDIR=
-target sun4 -c display_def.c
cc -0 -pipe -I/work/lmui/src/Xw -DAPPDEFAULTSDIR=
-target sun4 -c xwebster.c
rm -f xwebster
cc -o xwebster controlpanel.o display_def.o wordlist.o xwebster.o -0
-pipe /work/lmui/src/Xw/Xw/libXw.a -IXt -iXext -1X11
lmui@opal%

Once the you have edited the application defaults to reflect the location of the Webster
server, you can install the xwebster program system-wide by executing make install and
(optionally) make install.man as root. Then read the manual pageto learn how to run the pro-
gram and enjoy.

B.4 Another Example: xkeycaps

Before we end this appendix, let's show a more "standard" compilation. For this we choose
xkeycaps, a public domain program that's useful as a front end for the xmodmap program.
xkeycaps can be taken from export.lcs.mit.edu:
linui@ruby 35% ftp export.lcs.mit.edu
Connected to export.lcs.mit.edu.
220 export.lcs.mit.edu FTP server (NEWS-OS Release 4.1C) ready.
Name (export.Ics.mit.edu:Imui): anonymous
331 Guest login ok, send ident as password.
Password:
230 Guest login ok, access restrictions apply.
ftp> cd contrib
250 CWD command successful.
ftp> Is *keycaps*
200 PORT command successful.
150 Opening data connection for /bin/Is (ascii mode) (0 bytes).
xkeycaps.tar.Z
226 Transfer complete.
remote: *keycaps*
16 bytes received in 0.014 seconds (1.2 Kbytes/s)
ftp> bin
200 Type set to I.
ftp> get xkeycaps.tar.Z
200 PORT command successful.
150 Opening data connection for xkeycaps.tar.Z (binary mode) (121687 bytes).
226 Transfer complete.
local: xkeycaps.tar.Z remote: xkeycaps.tar.Z
121687 bytes received in 31 seconds (3.9 Kbytes/s)
ftp> quit
221 Goodbye.
lmui@ruby 36%

Now that we have it, unpack the compressedtar file, take a look at the resulting directory
contents.Once again, since there's a README, read it.

264 The X Window System Administrator's Guide

 lmui@ruby 36% zcat xkeycaps.tar.Z I tar xpf -
linui@ruby 37% Is -a
./ info.c kbd-ncd-vt220.h
../ ktd-atari-tt.h kbd-sco-HO.h
Imakefile kbd-dec-lk201.h kbd-sgi-iris.h
KbdWidget.c kbd-dec-lk401.h kbd-sony-nws.h
KbdWidget.h kbd-dell.h kbd-sun-type2.h
KbdWidgetP.h kbd-explorer.h kbd-sun-type3.h
KeyWidget.c kbd-hp-700x.h kbd-sun-type4.h
KeyWidget.h kbd-hp-720.h kbd-sun-type4ow.h
KeyWidgetP. h kbd-hp-pc. h SunOS. c
README kbd-ibm-rs6k.h version, h
actions.c kbd-ncd-nlOl.h vroot.h
all-kbds.h kbd-ncd-n!02.h xkeycaps.c
commands.c kbd-ncd-nl02fr.h xkeycaps.h
defaults.h kbd-ncd-n!02n.h xkeycaps.man
defining.txt kbd-ncd-n!02sf.h xkeycaps.tar.Z
guess.c kbd-ncd-nl0 8.h
hierarchy.txt kbd-ncd-n97.h
linui@ruby 38% more README

xkeycaps is a graphical front-end to xmodmap. It opens a window that looks

like a keyboard; moving the mouse over a key shows what KeySyms and Modifier
bits that key generates. Clicking on a key simulates KeyPress/KeyRelease
events on the window of your choice. It is possible to change the KeySyms
and Modifiers generated by a key through a mouse-based interface. This
program can also write an input file for xmodmap to recreate your changes
in future sessions. See the manpage for more details.

xkeycaps currently knows about the following types of keyboards:

Sun type2 (MIT layout) Silicon Graphics Iris/Indigo

Sun type3 (MIT layout) Sony NWS 1250

The README introduces the program, but doesn't include any build instructions. Look at the
Imakefile:
/**/# Imakefile file for xkeycaps, Copyright (c) 1991, 1992 Jamie Zawinski.
/

To specify a different default keyboard (for when the vendor display

string isn't recognized) do something like this:

KBELDEFINES = -DDEFAULT.J<BD_NAME=" \" Sun3 \""

to make there not be a default (meaning the keyboard must be specified

if the vendor display string isn't recognized) you can do

KBD_DEFINES = -DDEFAULT_J^BD_NAME=0

If you don't have the file Xll/DECkeysym.h (which comes with the MIT
distribution) then add ~DNO_DEC_KEYSYMS to DEFINES.

If you get a link error about _XInitKeysymDB being undefined, then add
-DNCLXInitKeysymDB to DEFINES. In this case, you might also want to
add -DKEYSYMDB=/some/file/XKeysymDB to DEFINES, to tell XKeyCaps where
the vendor-specific keysym database file resides. Otherwise, you will
have to set the $XKEYSYMDB environment variable before running this
program, or else it won't let you select from the set of vendor keysyms,

Compiling Public Domain Software 265

 Folks running R4 or older don't get to select from the set of vendor
keysyms anyway. If anyone comes up with a workaround to this, please
let me know.

If you have XTrap, add the line

#define HAVE_XTRAP

The XTrap support isn't quite finished yet.

/* #define HAVELJCTRAP */

This /makefile is somewhatmore "standard" than the xarchie /makefile, since it concentrates
on variables that affect the behavior of the application itself. We alter the /makefile to make
the default keyboard Ml 01, which is what most usersat our site have. To do so, we add the
following line towards the top of the /makefile:
KBD_DEFINES = -DDEFAULT_J<BD_NAME="\"N101\""

We poke around in lusrlindudelXl 1 and determine that we have DECkeysym.h installed.

Since we've never heard of XTrap, we assumewe don't have it. We now try to build the pro-
gram, heeding the /makefile warning that we might have a link error. In R5, xmkmf -a will
createthe Makefile and also run makeMakefiles, makeincludes and makedepend.
lmui@ruby 46% xmkmf -a
mv Makefile Makefile.bak
imake -DUselnstalled -I/usr/lib/Xll/config
make Makefiles
make includes
make depend
makedepend -s "# DO NOT DELETE" - -DDEFAULT_JKBD_NAME="\"N101\"" - \
xkeycaps.c KbdWidget.c KeyWidget.c info.c actions.c commands.c guess.c
SunOS.c
lmui@ruby 48%make
cc -O -pipe -DDEFAULT_£BD_NAME="\"N101\"" -target sun4 -c xkeycaps.c
cc -O -pipe -DDEFAULTJ(BDJflAME="\"N101\"" -target sun4 -c KbdWidget.c
cc -0 -pipe -DDEFAULT_JCBDJIAME="\"N101\"" -target sun4 -c KeyWidget.c
cc -0 -pipe -DDEFAULT_JKBDJMAME="\"N101\"" -target sun4 -c info.c
cc -O -pipe -DDEFAULT_j(BD_JIAME="\"N101\"" -target sun4 -c actions.c
cc -0 -pipe -DDEFAULT_JKBD_NAME="\"N101\"" -target sun4 -c commands.c
cc -0 -pipe -DDEFAULT_J(BD_fIAME="\"N101\"" -target sun4 -c guess.c
cc -0 -pipe -DDEFAULT_JKBD_NAME="\"N101\"" -target sun4 -c SunOS.c
rm -f xkeycaps
cc -o xkeycaps xkeycaps.o KbdWidget.o KeyWidget.o info.o actions.o
commands.o guess.o sunOS.o -0 -pipe -iXaw -iXt -iXext -iXmu -iXext -1X11

xkeycaps built without a hitch. Since there's no app-defaults file, we can try it out without
having to concernourselves with resourcedefinitions:
lmui@ruby 51% xkeycaps
xkeycaps: a keyboard type was not specified, and the vendor ID string,
"Acme X Servers, Tucson, AZ"
is not recognized. We will guess that you are using a keyboard of
type "N101." If this is incorrect, please supply the -keyboard
option with one of the following names:

266 The X WindowSystemAdministrator'sGuide

 Sun2 - Sun type2 (MIT layout)
Sun3 - Sun type3 (MIT layout)
Sun4 - Sun type4 (MIT layout)
Sun4ow - Sun type4 (OpenWindows layout)
N97 - Network Computing Devices N97
N101 - Network Computing Devices N101
N102 - Network Computing Devices N102
N102SF - Network Computing Devices N102 (Swedish/Finnish layout)
N102N - Network Computing Devices N102 (Norwegian layout)
N102F - Network Computing Devices N102 (French layout)
N108 - Network Computing Devices N108
NCD220 - Network Computing Devices vt220
LK201 - Digital Equipment Corporation LK201
LK401 - Digital Equipment Corporation LK401
RS6k - Inferior But Marketable RS/6000
SC0110 - Santa Cruz Operation 110
HP700X - Hewlett Packard 700X
HP720 - Hewlett-Packard 720
HPPC - Hewlett-Packard PC
TT - Atari TT
NWS - Sony NWS 1250
DELL - DELL PC
SGI - Silicon Graphics
Explorer - Texas Instruments Explorer

As the default, we get the N101 keyboard:

gj XKeyCaps;
Network
Computing
Devte««
N101
keyboard
(Quit) KeyCode:
(SelectKeyfao'ard) KeySym:
(TypeAt Window)
(Restore
Default
Map)AutoRepeat:
CWrtteOutput)
XKeyCaps
1.20;6 1991,1992JamieZawinski
<[email protected]>

F1 ||F2 IJF3IJF4I |F5 ||F6 ||F7 ||F8 I |F9 IIF10IIF11IIF12I lUneIiBrtallSetuJ

lp|| OF|| n|| 1F| I 27|| 2F|| 37|| 3F\ \ 47|| 4F|| 56|| SE| |FeS^||5F|[ 62|
~
Num : ;
^cxK 77 7E 64
7 i 9 "+
6C 75 7D
4
6B
Q 674 7C
r-]%- 3 Entei
69]| 72 7A
0
70 71 79

Figure B-2. xkeycaps window

When you decide to install xkeycaps,run both make install and make install.man as root. As
before, it's a good idea to check what's going to be installed before you actually do it, using
the -n option to make:
lmui@ruby 82% make -n install install.man
if [ -d /usr/bin/Xll ]; then set +x; \
else (set -x; /bin/sh /usr/bin/Xll/mkdirhier /usr/bin/Xll); fi

Compiling Public Domain Software 267

 install -c -s xkeycaps /usr/bin/Xll
echo "install in . done"
if [ -d /usr/man/mann ]; then set +x; \
else (set -x; /bin/sh /usr/bin/Xll/mkdirhier /usr/man/mann); fi
install -c -m 0444 xkeycaps.man /usr/man/mann/xkeycaps.n
echo "install.man in . done"

If this is fine with you, go aheadand install the program:

lmui@ruby 83% su
Password:
# make install install.man
install -c -s xkeycaps /usr/bin/Xll
install in . done
install -c -m 0444 xkeycaps.man /usr/man/mann/xkeycaps.n
install.man in . done
#

B.5 Related Documentation

imake is discussed in more detail in Section 8.7.

For more information on xmkmf, seeits manual page and Section 8.6.1 of this book.
The Whole Internet User's Guide & Catalog by Ed Krol (O'Reilly & Associates,1992).
Managing Projects with make, by Andy Oram and Steve Talbott (O'Reilly and Associates,
1991).

268 The X WindowSystemAdministrator'sGuide

 c

X on Non-UNIX Platforms

X runs on all types of hardware, on all sorts of operating systems. Both cli-
ents and servers run on IBM-compatible PCs running DOS, as well as Macin-
tosh computers. Full X distributions are available for NeXT machines, but
the servers have to negotiate with the NeXTStep interface. This chapter
briefly describes the X products available on those platforms.

In This Appendix:
X on DOS-based PCs 272
Requirements for PC X Servers 272
Installing and Configuring PC X Servers 273
Problems Particular to PC X Servers 274
X on Macintosh Computers 275
Macintosh-based X Servers 275
MacTCP and the Communications Toolbox 276

X on NeXT Computers 277

 c
X on Non-UNIX Platforms

This book concentrates on X as it runs on UNIX systems. But X is OS-independent. Our

office equipment consists mostly of UNIX systemsand X terminals, but we also have Macin-
tosh computers,PCs, and NeXT machines.X runs on all of them.

" We have one PC user who runs an X server on top of his Microsoft Windows environ-
ment. He runs PC applications locally, but also displays X windows alongside his
MS-Windows windows. He runs project managementsoftware on the PC, while he writes
and debugs UNIX programs and readshis mail using X applications.
" We have a diehard Macintosh user who runs an X server on top of his Macintosh operat-
ing system.He works primarily with Macintosh programs but occasionally needs to edit
troff files on a UNIX system and preview them with an X-based previewer.
" We have a NeXT user who runs a full X distribution on top of the NeXTStep environ-
ment. She uses the NeXT environment for its newsreader,dictionary, and mailer, while
she usesthe X environment for compiling and testing X programs.

Each of these usershas the advantage of keeping his or her favorite user environment, while
also maintaining the sameconnectivity that co-workers have with workstations or X termi-
nals.

Convenience is not the only advantageto running X on other operating systems.Probably the
most significant advantage is price. Offices can upgrade to X without having to invest in
new hardware. X server software might cost anywhere from $200 to $500, as opposed to
$1000 for a low-end X terminal. As for disadvantages ... X servers running on PCs and
Macs are noticeably slow compared to X terminals, sometimespainfully slow. PC monitors
are generally smaller than X terminal monitors and the resolution is much worse. And the
low-cost advantageisn't always valid, since a PC has to meet many requirementsbefore an X
server can run with reasonableperformance.
Currently, the PC and Macintosh users at our office run only X servers,relying on a UNIX
host to run clients for them to display. However, X clients and libraries have recently been
ported to the PC platform (notably with Quarterdeck's Desqview/X product), and Macintosh
X clients are also available. This gives us the ability also do it the other way around-that is,
to display display both PC and Macintosh programs on X terminals. The potential is
immense. X allows the sort of interconnectivity between operating systemsthat was previ-
ously limited largely to file sharing and remote logins.

X on Non-UNIX Platforms 271

 Since there are so many products out there, this appendix only covers generalities about X
running on other platforms. For more information, look for the monthly posting on comp.win-
dows.x on X servers for PCs, Macs and Amigas. This document is also kept on
export.lcs.mit.eduin the file IcontriblXServers-NonUNIX.txt.Z.

C.1 X on DOS-based PCs

Most X software available on PCs running DOS is server software. There are two types of
PC X serverson the market: those that run on top of DOS directly, and those that run on top
of Microsoft Windows.

The X servers that run on top of DOS replace the entire desktop, and returning to DOS
usually requires exiting (or suspending)X. The X serversthat run on top of Windows, on the
other hand, provide an integrated environment with accessto both X and Microsoft Windows
applications simultaneously. Some Windows-based X servers also let you cut-and-paste
between the X environment and the Windows environment.

If the PC will be used primarily for running X-that is, as an economical X terminal-then
the DOS-basedX serversare probably sufficient for your needs.If the PC will frequently be
used to run Windows applications as well, however, Windows-basedX servers give you the
best of both worlds.

Desqview/X by Quarterdeck Office Systems provides the first distribution of both X clients
and servers for PCs running MS/DOS.Desqview/X runs on top of Quarterdeck's Desqview
multi-tasking GUI, integrating DOS applications, MS-Windows applications, and X applica-
tions. You can use Desqview/X to remotely execute PC applications as X clients and display
them on any connectedX server.

C.1.1 Requirements for PC X Servers

We mentioned that PCshave to meet serveral requirements before they can run X servers. In
general, before you can run a PC X server,you have to meet the following requirements:
Processor The PC should have a 80386 or '486 CPU processor.(Some vendors also support
'286 machines, but no one recommends it.)

Monitor The PC needsan enhancedvideo display. Most vendors require either a VGA or
Super VGA display. Some vendors also support EGA and 8514 graphics. Note
that what the PC world calls a "high resolution" monitor still has lower resolu-
tion than a low-resolution X terminal.

Mouse The PC must have a two-button or three-button mouse.

Memory The PC must have 640K bytes of base memory, plus either 1.4 megabytes of
usable extended memory for DOS-basedX servers,or 2 megabytesof memory
for Windows-based X servers.

272 The X WindowSystemAdministrator'sGuide

 Disk Space The PC must have a hard disk with at least 3 megabytes of free disk space
(sometimes up to 5 if you want all the fonts installed).
Networking The PC needs to have TCP/IPinstalled. Some vendors supply TCP/IPpackaged
with the X server, but most of those that do charge extra for it. Furthermore,
beware that not all implementations of TCP/IP are equal-if you have other
applications on your PC that require TCP/IP,you may find that a vendor's propri-
etary version does not work properly with them. Networking packagessupported
by most vendors are FTP Software's PC/TCP, Excelan's LAN Workplace Net-
work Software for PC DOS TCP/IPTransport System, and Sun Microsystem's
PC-NFS. (Other frequently supportedTCP/IPpackages are Beame & Whiteside
and WIN/TCP.)

Ethernet Card
The PC requires an Ethernet card supportedby the selectedTCP/IPpackage. Not
all Ethernet cards are equal, but most TCP/IP vendors support 3COM, DEC
DEPCA, Intel PC586, Ungermann-BassNIC, Western Digital, and the XIRCOM
Pocket EthernetAdapter.
Be aware of theserequirements before you invest in PC X serversfor your site. It may turn
out that it's cheaper to buy an X terminal.

C.1.2 Installing and Configuring PC X Servers

Installing and configuring the actual PC X servers themselves is generally a breeze. Most
packagesare designed to be installed with one command,prompting for information as you
go along. The procedure varies from manufacturer to manufacturer, but you usually need to
supply the following in order to complete installation:
" Type of VGA monitor
" Resolution of VGA monitor

" Type of TCP/IPpackage (Note that if the one you have isn't listed as an option, you're out
of luck.)

" Name and IP addressof PC. (You may have to give it the pathnameof your hosts file on
the PC.)

" Name and IP address of the name server

" An accesscontrol list (if applicable). (Some products provide their own host-basedsecu-
rity by allowing only the listed hosts to connect to the server.)
In addition, you can choosethe following preferences:
" Virtual screen,for X servers that supportit. This meansthat the X server will pretend that
your screenis larger than it is, with a portion of the "virtual" screenhidden but accessible
by moving the mouse to that area. This is useful if you are running any applications
requiring a full-page display on a standardsizedmonitor.

X on Non-UNIX Platforms 273

 " Session startup with XDMCP (for those that support it) or with remote execution. We
strongly recommendusing XDMCP.SeeSection 3.3 for information on setting up xdm.
Most manufacturers will happily provide technical support if you have problems. We
strongly advise calling the manufacturer if you have problems getting a PC X server to work.
Manufacturers are the ones who is most likely to be aware of incompatibilities between their
product and other software you have installed on your PC.
As far as the network is concerned,if you can ftp or telnet to the host machine from the PC
using the software that came with your TCP/IPpackage, you don't have to do any other confi-
guring from the PC end for the X connection to work. On the host end, you needto enter the
PC's IP addressinto the network configuration, as you would for an X terminal; see Section
A.6 for more information.

Windows-based X servers may require some special network configuration before they will
run properly. The way this is done is heavily dependent on your vendor's implementation,
but it may involve changes in both the Windows configuration file win.ini and in
autoexec.bat.

C.1.3 Problems Particular to PC X Servers

The following are problemsthat we've encounteredwith PC X servers:

" Most PC X servers give you 4 bits per pixel for color displays. This confusesmany X
programs. SeeSection 7.1.1.3 for more information.
" If you use remote execution to start your X sessioninstead of xdm, you might have a spe-
cial problem with xrdb. Most PC X servers reset the server when the last X client has ter-
minated. This is fine, except that it puts you in a Catch-22 situation with xrdb: you want
xrdb to run and complete executing before you run any other clients (since you need to
have those resources loaded), but then the server resets,losing all the resourcesyou just
loaded!

There are many solutions to this problem if you don't want to just use xdm. Probably the
easiest solution is to use the -retain option to xrdb. Another is to use rexec to run a script
rather than individual X clients. A third option is to start up a "dummy" client to keep
running while xrdb does its stuff, preferably one whosedefaults you don't mind.
" Some PC TCP/IPproducts limit the number of connections allowed. For example, FTP
Software's PC/TCPlimits the PC to four TCP/IPconnections, which isn't enough for any
decent X session.You have to see your TCP/IPvendor's documentation for information
on how to increasethis default. For PC/TCP,the solution is to start up the kernel program
in autoexec.bat using the -t option to specify the number of connections to allow. For
example, for our 3COM 3c501 Ethernet card, the command was:
3c501 /t 8

This increasedthe number of TCP/IPconnectionsto eight.

274 The X Window System Administrator's Guide

 C.2 X on Macintosh Computers

Full X distributions are available on Macintosh computers that run UNIX as well as the Mac-
intosh OS. Two UNIX products for the Macintosh are System-V basedA/UX by Apple Com-
puter, and BSD-basedMachTen from Tenon Intersystems.
If you don't have a full UNIX distribution, you can still run an X server,or set up the Macin-
tosh to run an X client. There are currently two X serverproducts for the Macintosh: MacX
and eXodus. MacX is a Macintosh X serverthat is available from Apple Computer (it is also
bundled with their System V-based UNIX operating system,A/UX, as of version 2.0.1). eXo-
dus is a Macintosh X server distributed by White Pine Software.
There are also currently two X client products for the Macintosh: Planet X and Xgator.
Planet X is distributed by InterCon Systemsand Xgator is distributed by Cayman Systems.
The advantage of a Macintosh X client is that you can run Macintosh programs on your X
terminal. Unfortunately, only one user can accessthe sameMacintosh at a time, so the Mac-
intosh becomes disabled while the X client is running, and no other X userscan start up the
client software while someoneelse is using it.
Macintosh-basedX servers and clients alike require either a direct Ethernet connection or a
LocalTalk connection to a LocalTalk/IP gateway such as Cayman's GatorBox. The Commu-
nications Toolbox must also be installed (standard with System 7), with the MacTCP tool
installed and configured properly.* (eXodus works with DECnetas well as TCP/IP.)

C.2.1 Macintosh-based X Servers

Both X servers for the Macintosh, MacX and eXodus, can run either "rootless" or "rooted."
By "rootless," we mean that X clients open directly on the Macintosh desktop, intermixed
with other Macintosh windows. The Macintosh OS acts as a window manager for both X and
Macintosh windows. By "rooted", we mean that a typical X root window is active, either
enclosedentirely within a Macintosh window, or available through a pull-down menu. An X
window managercan be used in a rooted window (such as twm, mwm or olwm).

Some X programs may have problems with a rootless environment; to run those programs,
use rooted screensonly. MacX defines 4 screens:screen0 is rootless monochrome,screen 1
is rooted monochrome, screen 2 is rootless color, and screen 3 is rooted color. eXodus allows
you to define up to 6 screensas either rooted or rootless.
One of the most obvious problems with using a Macintosh as an X server is that the Macin-
tosh mouseonly has one button. MacX usesthe left-arrow and right-arrow keys to act as the
second and third mouse button (respectively). eXodus provides a little more flexibility for
configuring mousebehavior. In addition, there are third-party mice for Macintosh computers
that have two or three buttons.

*SLIP has also recently become available for the Macintosh.

X on Non-UNIX Platforms 275

 (Users of OPEN LOOK programs can use the props utility to change the behavior of the
SELECTmouse button so that it brings up menus instead of selecting the default item when
pressedon a menu button. This is a good tip for all 1- and 2- button mouse users. Mac users
who also run olwm might also want to use props to turn off "pointer jumping," by which
olwm and olvwm move the mouse pointer automatically to follow scrollbars and pop-up
notices.)

You can get upgrades to MacX from aux.support.apple.com, in the Iaux.patcheslsup-

ported!MacX directory. You are encouraged to retrieve the MacX upgrades only if you
already have a legal license for MacX. (Only the server is redistributed on the ftp site, which
is uselesswithout the fonts or a font conversion utility anyway.)
If you use either MacroMaker or QuickKeys on your Mac, it is strongly recommendedthat
you disable it. MacroMaker and QuickKeys translate keystrokes, conflicting with the X
server.

C.2.2 MacTCP and the Communications Toolbox

To run Macintosh X products, you generally need to have MacTCP running. MacTCP was
developed by Apple, and is distributed by severalthird-party vendors. It is also bundled with
MacX.

MacTCP runs under the Communications Toolbox. The following tips are important to note
when installing MacTCP:
1. You must install the Communications Toolbox correctly. Under System 7, the Commu-
nications Toolbox is already installed as part of the base OS distribution. If you needto
install the Communications Toolbox for a Macintosh that is not running System 7, how-
ever, you can't simply create a Communications folder under your System folder and
copy the MacTCP tool in there. You must run the installation utility that is bundled with
the Communications Toolbox.

If you don't install the Communications Toolbox correctly, you'll never get a message
that tells you it's improperly installed. Instead, you'll get an error messagesuch as "No
Communications Tools Installed," which misleadingly implies that the Toolbox is
installed correctly but MacTCP isn't.
2. You need to copy the MacTCP tool to the new Communicationsfolder within the system
folder, and copy the MacTCP and AdminTCP files to the System folder (under System 7,
these files reside in the Control Panels folder). We strongly recommend that you do not
copy thesefiles from another Macintosh, but take them directly from the distribution flop-
pies. If you do copy them from another Mac, make sure not to take the MacTCP Prefer-
ences file.

3. Configure MacTCP using the AdminTCP control panel document. (AdminTCP is identi-
cal to MacTCP, except that you can use AdminTCP to lock the configuration after it is
properly configured.) Here is where you specify things like your IP address,subnetmask,
name server, etc.

4. Reboot and try running a MacTCP program.

276 The X WindowSystem Administrator'sGuide

 5. Once you have confirmed that MacTCP is properly configured, put a lock on it and throw
the AdminTCP file in the trash.

A possible conflict with MacTCP is that if you are also running NCSATelnet, you need to be
sure that you are running the version that is MacTCP-compatible. That meansthat you need
to install the version of NCSA Telnet entitled something like Telnet 2.4 - MacTCP. If you
don't do this, then after running an application that usesMacTCP, you won't be able to run
NCSATelnet again until you reboot.
Notes on configuring MacTCP are available on sumex-aim.stanford.edu in the file linfo-
maclreportlmac-tcp-info.txt.

C.3 X on NeXT Computers

The NeXT machine does not technically belong in a chapter about non-UNIX machines,since
it is based on UNIX. The NeXT machine also has built-in Ethernet and TCP/IP, so a lot of the
issuesfor running X on PCs and Macs don't apply to the NeXT. However, we discuss them
here because NeXT X distributions are a different breed from other UNIX distributions, since
they have to deal with the NeXTStep interface.
A public domain R4 X distribution for the NeXT called XNeXT is available through anony-
mousftp from cunixf.cc.columbia.edu. (Although an R5 server is currently available for the
NeXTstation Turbo, it is not yet available for other NeXT machines.)

There are also three commercial products for the NeXT. Theseare co-Xist by Pencom Soft-
ware, Cub'X by Cub'X Systemes (distributed in the U.S. by Interactive Technology), and
eXodus from White Pine Software. Cub'X and co-Xist are full X distributions including
servers, clients, and libraries, with OSF/Motif clients and libraries also available. eXodus is
just a serverwith a select group of clients.
All three commercial implementations meld X with the NeXTStep interface much in the way
Macintosh and Windows-based X servers do, in a "rootless" mode. XNeXT, on the other
hand, supplants the NeXTStep interface and requires you to "hot-key" to switch between the
two modes.

Regardlessof what X server you choose to run on the NeXT, you should make sure that the
second mouse button is enabled in NeXTStep (through the Preferencesapplication), or it
won't be available to the X server.

X on Non-UNIX Platforms 277

 D

Resources and Keysym Mappings

Resources and keysym mappings are topics that the administrator needs to
be familiar with in order to configure applications and set up user environ-
ments. This appendix gives some background material on both of those top-
ics.

In This Appendix:
Using Resources 281
Resource Definition Syntax 281
Loose and Tight Bindings 282
The -name Command-line Option 283
xterm Versus XTerm 283
Where Resources Are Defined 285
Advantages of xrdb 287
Translation Tables 288
Defining Keys and Button Presses With xmodmap 290
Using xev to Learn Keysym Mappings 292
Related Documentation . .. 293
 D
Resources and Keysym Mappings

Two important pieces to the X puzzle are resources and keysym mappings. Although these
two issues are unrelated, they both come into play when administrators have to debug user
environments or configure applications system-wide. This appendix gives some background
material on both of thosetopics.
Resourcesare covered in detail in Volume Three, X Window SystemUser's Guide, by Valerie
Quercia and Tim O'Reilly (O'Reilly & Associates, 1990). Some of the material in this chap-
ter repeatswhat you'll find there, but we also give some useful tips and advanced informa-
tion for administrators. Even if you are familiar with how to use resources,you may want to
scanthis appendix.

D.1 Using Resources

Resourcesare tricky to deal with, but understandinghow they work is extremely important
for X administration. They are used for configuring not only everyday clients like xterm and
xclock, but also special clients such as window managersand the X Display Manager (xdm).
Resource syntax is used even by some X terminal vendors for configuring the X server
remotely. For thesereasons,we think it's worth it to cover resourcedefinition in depth.

D.1.1 Resource Definition Syntax

The syntax for defining resources can be quite complex, requiring some familiarity with
widget hierarchies. For our purposes,however, it will suffice to know that the syntax for a
simple resourcefollows the form:
name*variable: value

For example:
xt erm*background: cadetblue
xterm* foreground:deeppink

specifiesthat the client named xterm should use a background color of cadet blue and a fore-
ground color of deep pink. Similarly, you can specify a specific font with:
xterm*font:-schumacher-clean-bold-r-normal-16-160-75-75-c-80-iso8859-l

Resourcesand Keysym Mappings 281

 If you want the client namedxbiff always to appearin a certain spot, you can have:
xbiff*geometry:+750+900

Resource definitions can be commentedout by preceding them with exclamation points (!),
and definitions can span multiple lines by using a backslash (\) to suppressnewlines. Note
that if a resource cannot be properly interpreted-for example, if you forget the colon
between the variable name and the value-no error messageis generated,but the entry is
simply ignored.
There are additional syntax rules if you are loading your resources directly into the server
with xrdb, since xrdb runs the file through the C pre-processor (cpp) as well. See Section
D.I.3 for more information.

D.1.1.1 Loose and Tight Bindings

The asterisk (*) between the name of the client and the variable to be specified meansthat
these definitions are using loose bindings, which are recommendedfor general use. The true
name for a resource, using tight bindings, might be something much more complicated, del-
imited with periods between each field, suchas:
Xwebster.panel.display_scroller. display.alignment: Left

but in most situations, you can shortenthis to:

Xwebster*alignment: Left

(One notable exception we make to this rule is with the XTerm*VT100 .geometry
resource definition. This is becausewhereasthe VT100 widget for xterm uses the size of a
character for the window geometry, other widgets within xterm use pixels. If you specified
90x40 as the window size for all xterm widgets, xterm menus would appear unusually
small.)

A full explanation of the syntax of resourcevariables and their precedencecan be found in

The X Window SystemUsers Guide. For now, just know that when you use the asterisk in a
resourcename, you may be matching severalfields at once.
As you would expect, if you omit the client name and simply start the resource definition
with an asterisk, then all clients inherit that resource definition. That is, should you define a
global resourceas:
*geonetry:+0+0

then all clients would appearat coordinates (0,0) by default.

However, the asterisk does not work like the shell wildcard it resembles. You cannot use it as
a general-purposewildcard in resourcedefinitions. The asterisk can't be used to match par-
tial namesof fields, but only as a replacement for complete fields in the resourcename. That
is, if you want both xterm and xtetris to appear with yellow backgrounds,you cannot simply
write:

xt*background :yellow

This resourcedefinition would not affect xterm or xtetris; it would affect only a client with
the name xt. The reason for this is simple: you wouldn't want loosely-bound resourcesset for

282 The X WindowSystemAdministrator'sGuide

 the xcal calendar program, for example, to affect the behavior of the xcalc calculator pro-
gram as well.
A resource can be overridden by a more specific resource-for example, if you set the fol-
lowing resources:
xterm*background: blue
xterm. VT10 0.background: red

and then open a standardxterm window with the VT100 widget, the second declaration is
more specific than the first and the window background will appear in red. However, note
that any other xterm widgets, such as mainMenu, will appearwith a blue background.
In R5, the question mark (?) character is introduced in resourcenames. A question mark in a
resourcename representsexactly one field in a loose binding. Loose bindings using question
marks are considered to be more specific than bindings using only asterisks. Bindings with
question marks will therefore take precedenceover other loose bindings.

D.1.1.2 The -name Command-line Option

An X toolkit option that has an important effect on which resourcesa client usesis the -name
option, which effectively changesthe name of the client. By changing the name of the client,
it changesthe name of the resourcesit acceptsas well.
The possibilities available with the -name option are best illustrated by example. A user
might want to have xterm windows from a host called sapphire with a blue border, but win-
dows from host ruby with a red border. There are multiple ways of doing this, but one way
might be to define the following resourcesto be accessedby all xterm clients:
xterm-sapphire*BorderColor: blue
xterm-ruby*BorderColor: red

and then start up the windows with -name options, to give the window from machine ruby
the name xterm-ruby and the window from the machine sapphire the name xterm-sapphire.
% xterm -name xterm-ruby &
% xterm -name xterm-sapphire &

Although the -name option for the xterm client changesthe string in the titlebar as well, it
should not be confused with the -title option, which changesthe string in the titlebar but does
not change the name of the client itself.

D.1.1.3 xterm Versus XTerm

Although we'd like to avoid all the complexities of how resources are named, there is one
detail that we can't escape. Sometimes the name xterm is used in resource names, and
sometimes XTerm is used. Although this usage seems arbitrary, it isn't at all, and the two
terms should not be confused.

The name of your window is usually the name of the client; that is, if you just run xterm, the
window that comes up will have the namexterm. As described above,however, you can use
the -name toolkit option to change the name of the window. For example, if you are running
a console window (started with the -C option to xterm), you might want to name that window

Resourcesand Keysym Mappings 283

"CONSOLE."Similarly, if you are running a window with a particularly large geometry,you
might want to name it "bigxterm." You can start the clients with the -name option shown
above:

% xterm -name CONSOLE

% xterm -name bigxterm

and then use thesenamesin resource specifications,such as:

CONSOLE*font: fixed
bigxterm*geometry: 14 0x6 0

Resourceswritten with the name CONSOLE will apply only to windows with the name CON-
SOLE, and resourceswith then name bigxterm will apply only to windows with the name
bigxterm. However, although the bigxterm and CONSOLE windows have different names,
they can both be considered instancesof a larger class, called XTerm. All windows begun
with the xterm client belong to the class XTerm, and any resources written for the name
XTerm will apply to all xterm windows, whether their name is CONSOLE, bigxterm, goofy,
dumbo, or just plain xterm. Note also that they would apply to the xterm-ruby and xterm-sap-
phire windows shown in the previous example. The following resourcedefinitions:
XTerm* scrollbar:true
XTerm*font:-schumacher-clean-bold-r-normal-16-160-75-75-c-80-iso8859-l

would apply to both the CONSOLE and bigxterm windows, with one caveat: since the font
for CONSOLE is explicitly redefined to "fixed" as shown earlier, it will ignore the
XTerm* font definition, becausewhen all else is equal (i.e., the bindings are the same),
instance specificationsoverride class specifications.

Learning the Class and Instance Names

Knowing the class name for a given client is important in order to set client-specific
resources. The manual page should also tell you the class name; but another way to
learn the class name for a given window that is currently displayed is to use the xprop
client, which among other things lists a WM_CLASScategory. In that category, the first
name listed is the name of the particular window, and the second name is the name of
the class. For example:
% xprop -name bigxterm

wn_CLASS(STRING) = "bigxterm", "XTerm"

twm users can also use the f. identify function to learn the class name for a window.
Seethe twm manpagefor more information.

This is only one example of instancesand classes. Within the application itself, classesare
used to group together severalproperties. For example, the xterm client considers the color of
the text, the pointer color, and the text cursor color to all be instances of the same class,
called Foreground. The following resource:
xterm*foreground: red

284 The X WindowSystem Administrator'sGuide

 only changesthe color of the text. But the resource:
xterm*Foreground: red

changesthe color of the text, the pointer, and the text cursor all to the same color. This is
equivalent to:
xterm*foreground: red
xterm*pointerColor: red
xterm* cursorColor: red

D.1.2 Where Resources Are Defined

For each client application, there are dozensof available resources,and any number of ways
to specify them. The behavior you want may depend on what host the client is running on or
what X server is used, or just on your personal preferences. For that reason, a client's
resourcescan be set at the system level, at the server level, and at the user level. Therein lies
the problem: since there are so many ways resources can be defined, tracing their definitions
can be a frustrating task.
Upon startup, clients build the resourcedatabase.The resourcemanagersearchesfor resource
variable definitions in multiple places and then passesthose variable definitions back to the
client program. The resource manager typically searches in the following places for
resources,with later definitions overriding earlier ones:
1. System-wide application defaults, in lusrllib/Xlllapp-defauhsl directory. The name of
the file used for application-specific defaults is the name of the client class,not the client
itself. For example, lusrlliblXll/app-defaults/XTerm contains application defaults for the
xterm client. Note that the app-defaults resourcesare read only by clients that run on that
particular host, regardlessof where they display.

2. User-specific per-application defaults, usually in a user's home directory. For example,

$HOME/XTerm on a given host is read by all xterm clients started on that host by a partic-
ular user. If your home directory is shared among multiple hosts, therefore, that single
XTerm file can specify resourcesused by all xterm clients on each of those host machines.
3. Host-specific defaults (not specific to an application), usually in a user's home directory.
For example, $HOMEI.Xdefaults-sapphireis read by all clients running on the machine
sapphire. 'This means, for example, that even if your home directory is shared among
multiple hosts, you can have xterm windows appear in one font on one machine, in
another font on another machine, and in reverse video on a third machine-simply by
having multiple Xdefaults-hostname files in your home directory. The name of the file
used for system-specific defaults can be redefined with the XENVIRONMENTenviron-
ment variable; for example, if you were to set XENVIRONMENTto My.resources, the
resourcemanagerwould look in that file instead.
4. Resourcesloaded directly into the server (into the resource database) with the xrdb cli-
ent. This means that you can have all xterm clients from any host use the same fore-
ground, background, fonts, etc., without having to maintain $HOMElXdefaults-hostname
files for each machine, or multiple $HOMEIXTerm files if your home directory is not

Resourcesand Keysym Mappings 285

 shared among multiple hosts. In general, the preferred way of specifying a reasonable
number of resources for a user is to use xrdb.

The xrdb client is typically run in the user's startup script, e.g., .xsessionor .xinitrc, to
load a resource file (any filename can be used, but common names are .Xresourcesand
Xdefaults}. An administrator can also set up a default resource file for all users, to be
read by xrdb in the systemwide startup script (for sessionsstarted with xdm, this would be
lusrlliblXlllxdmlXsession}. Note that resources loaded into the resource database are
still read only at client startup: a change will affect only subsequentclients, not clients
already running.
5. If no resourcesare loaded directly into the server (i.e., if xrdb has not been run), defaults
are read from a file called .Xdefaults, usually in the user's home directory. Note that this
means that clients run from different hosts may use different resources if your home
directory is not sharedamong machines.
6. Resourcesloaded directly on the command line, using the -xrm option.

In the list above, we say that some default files are "usually" read from a user's home direc-
tory. The directory in which you keep your application defaults is assumedto be your home
directory. The XAPPLRESDIRenvironment variable comes into play here-if you set XAP-
PLRESDIRto $HOMEIXstuff, the resource manager will look under that directory for client-
specific resource files (such as XTerrri). Other environment variables that affect where
resources are read from are XFILESEARCHPATH and XUSERFILESEARCHPATH.

Seeing Where Resources are Read (SunOS, Solaris, SVR4)

To see what resourcefiles are read on client startup, try using the trace command on a
SunOSmachine, or the truss command on a Solaris 2.0 or SVR4 machine. For example:
lmui@ruby% trace xtenn >& /tmp/xterm.trace

Then examinethe resulting file:

gethostname ("", 1002) = 0
open ("/home/limi/.Xdefaults-ruby", 0, 017777777) = -1 ENOENT (No such
file or directory)
access ("/home/lmui/XTerm", 04) = -1 ENOENT(No such file or directory)
access ("/usr/lib/Xll/app-defaults/XTerm11, 04) = 0
stat ("/usr/lib/Xll/app-defaults/XTerm", Oxf7ffed90) = 0
open ("/usr/lib/Xll/app-defaults/XTerm", 0, 036734323664) = 4
stat ("/usr/lib/Xll/app-defaults/XTerm", Oxf7fff200) = 0
read (4, "*SirtpleMenu*BackingStore: NotUse".., 2800) = 2800
close (4) = 0

In the example, note that the user had resourcesloaded into the server, so $HOMEIXde-
faults was not opened.The only resource file in its path that it found and openedwas the
system-wideapp-defaultslXTerm file.

286 The X Window System Administrator's Guide

D.1.3 Advantages of xrdb

Using xrdb to load your resourcesdirectly into the X server is the preferred way of allocating
resources. Using xrdb helps to make things more consistent-clients run from a host on
which you have a different home directory (thus different $HOMEi.Xdefaults files) are
guaranteedto use the sameresourcesif all your resourcesare kept directly in the server.
One of the most powerful things about xrdb is that it gives you special flexibility since it runs
the resource file through a C pre-processor(cpp by default). Using cpp means that you can
have #if def and ^include commandsin your resourcefiles, and that you can use the -D
and -U options to define and undefine symbols.

For example, you can call xrdb with the -D option to set defaults according to the current
hostname:

xrdb -D"hostname" -merge $HOME/.Xdefaults

This allows us to set up our .Xdefaults file with different defaults for different hosts. (On a
system that doesn't have the hostname command, you might use uname -n.) For example,
your .Xdefaultsfile might contain:
! ruby windows with red borders
#ifdef ruby
XTerm*bordercolor:red
#endif /*ruby*/

! sapphire windows with blue borders

ttifdef sapphire
XTerm*bordercolor:blue
#endif /*sapphire*/

You can also do somefancy stuff with setting colors or fonts "consistently." For example, if
you like to use fonts in the samefamily, you might do:
#define SMALL -schumacher-clean-medium-r-normal--10-100-75-75-c-80-iso8859-l
tdefine BIG -schumacher-clean-medium-r-normal-16-160-75-75-c-80-iso8859-l

smallxterm*Font: SMALL
Xconsole*Font: SMALL
bigxterm*Font: BIG

Under R5, xrdb becomes much more powerful since it now pre-defines several useful sym-
bols, such as COLOR.
#ifdef COLOR
xterm*background: yellow
#else
xterm*background: white
#endif

Other useful symbols are PLANES,HEIGHT,WIDTH,SERVERHOST,

and CLIENTHOST.
A commonmistakein definingresourcesis to try to commentout lines usingan initial hash

Resourcesand KeysymMappings 287

 sign (#) instead of an exclamation point (!). If you then run the resource file through xrdb,
you'll get the error message"Unknown preprocessor directive" or "undefined
control."*

There are two ways to load resourcesusing xrdb:

xrdb -load filename
The resourceslisted in the specified file replace all resourcesalready loaded into
the server. All previous resources are erased. This is the default behavior of
xrdb.

xrdb -merge filename

The resources listed in the specified file are merged into the list of resources
already loaded into the server. New resource definitions with names matching
previous definitions will take precedence,but any resources that are not rede-
fined are retained.

The -query option to xrdb shows you all resourcescurrently set for your server.

D.1.4 Translation Tables

An important type of resource for many applications is a translation, with which keystokes
and mousebuttons can be defined within an application. (Note that this is distinct from rede-
fining keystrokesand button pressesat the server level, which is controlled by the xmodmap
client, described in Section D.2.) You can also use a translation table to change the action a
client performs when a particular event is reported.
Translations are best describedby demonstrating their use in a common application. A client
that defines a lot of translations is xcalc. The xcalc window generally resemblesthe window
shown in Figure D-1.
Each of the buttons shown in the xcalc window is defined using a translation table. The app-
defaults/XCalc file defines the fourth row of keys on the standardxcalc keypad with the lines:
XCalc.ti.button!6.Label:PI
XCalc.ti.buttonl6.Translations:#override<BtnlUp>:pi()unset()
XCalc.ti.buttonl?.Label:x!
XCalc.ti.buttonl7.Translations:#override<BtnlUp>:factorial()unset()
XCalc.ti.buttonlS.Label: (
XCalc.ti.buttonlS.Translations:#override<BtnlUp>:leftParen()unset()
XCalc.ti.button!9.Label: )
XCalc.ti.button!9.Translations:#override<BtnlUp>:rightParen()unset()
XCalc.ti.button20.Label: /
XCalc.ti.button2 0.Translations:#override<BtnlUp>:divide()unset()

* Some X applications edit resource files, often removing comment lines. If you use such an application, you might
want to fake a comment using resourcesyntax:

Comment.linel: This is a comment

This takes advantage of the fact that invalid resources are simply ignored by applications.

288 The X WindowSystemAdministrator'sGuide

 Calculator

I DEG

Figure D-1. xcalc window

Each button is given its label (e.g., PI for the first button), followed by the event translation
when it is pressed.In the case of the 16th button, the internal function pi() is called, presum-
ably returning the value of n. (Since the foreground and background colors are reversedon
the button when it is initially pressed,the Athena Command widget action unset() is then
called, returning the button colors to the default.) For the 20th button, "/" is the label, and
pressing it calls the divide() function. Clearly a user could easily redefine the behavior of
each button on the xcalc keypad by switching the translations in their own resourcefiles. (Be
sure to switch the labels too, though!)

Also in the XCalc application defaults file is a full translation table for interpreting keys-
trokes within the xcalc window:

XCalc.ti.bevel.screen.LCD.Translations:#replace\n\
Ctrl<Key>c:quit()\n\
Ctrl<Key>h:clear()\n\
None<Key>0:digit(0)\n\
None<Key>l:digit(1)\n\

<Key>KP_0:digit(0) \n\
<Key>KP_l:digit(1) \n\

<Key>KP_9:digit(9)\n\

<Key>KP_pivide: divide () \n\

<Key>.:decimal()\n\
<Key>+:add()\n\
<Key>-:subtract()\n\
<Key>*:multiply()\n\
<Key>/:divide()\n\
<Key>(:leftParen()\n\
<Key>):rightParen()\n\
<Key>!:factorial()\n\

Resourcesand KeysymMappings 289

 <Key>p:pi()\n\

<BtnlDown>,<BtnlUp>:toggle()selection()\n

These definitions allow you to type a "1" on the keyboard (either on the keypad or on the
main part of the keyboard) rather than clicking the correct button in the xcalc window. They
also allow keyboard shortcuts to many of the functions. You can accessthe divide () func-
tion by pressing a slashon either keyboard or keypad. You can get the value of n by pressing
a "p," and get the factorial of a number by pressing an exclamation mark. As you could
expect,this translation table can also be redefined at the user level.
Beware that translations are very specific about their syntax. A single spaceafter one of the
trailing backslasheswill cause the resource manager to ignore all subsequenttranslations,
with no error message reported.

For full information on the syntax for event translation resources,see the X Window System
User's Guide. For now, administrators should just be aware that translation tables are poten-
tially another tool in customizing a client for a user.

D.2 Defining Keys and Button Presses With xmodmap

An important piece to the X puzzle is filled by the xmodmap client. When the user performs
any action-such as typing a key or moving the mouse-the server sendsa packet of infor-
mation to the client called an event. Theseevents are then translated into actions by the cli-
ent. You can use the xmodmap client to effectively change the event that is reported to the
client.

Keysym mappings are mappings of keyboard events at the server level, before the event is
sentto the client. Keysyms are the symbols used for each key on the keyboard.
The X servermaintains a keymap table which contains a listing of keys on the keyboard and
how they should be interpreted. A client gets the keymap table from the server upon client
startup. In most cases,the keymap table is used to interpret keys literally-when you press
the letter "a," a key code is sent to the client which correspondsto the letter "a" in the key-
map table.

You can use the xmodmap client to reassignkey codes within the keymap table, xmodmap
can therefore be used to redefine how a key is interpreted by the client. You probably
wouldn't want to translate the alphanumeric keys on the keyboard, but you may want to
translate others. For example, you might want to change the Backspace key to a Delete:
% xmodmap -e "keysym Backspace = Delete"

Another example is if you mistakingly hit the CAPSLOCK key a bit too often, you can dis-
able it completely. Some people might disable CAPSLOCK the low-tech way (by just remov-
ing the key from the keyboard!), but you can also render it harmless with the command:
"
% xmodmap -e "keysym Caps_Lock =

effectively disabling the CAPS LOCK key entirely. Note that the symbol is now gone and
can't be redefined without using the hardware key code.

290 The X WindowSystemAdministrator'sGuide

If you are a DVORAK typist, you can usexmodmap to translate every key on the keyboard so
your QWERTYkeyboard behaveslike a DVORAKkeyboard.

If it everseemsthat keystrokesarenot workingcorrectly,youcancheckcurrentkeysymset-

tings by running xmodmap with the -pk argument.Use the xev client if you need to determine
exactly what keycode a key generateson your display. There is also a public domain client
called xkeycaps that can be used to display the keysyms for selected keyboards,as shown in
Section B.4.

You can use xmodmap to add or remove keysyms, or even to redefine the keycode associated
with that keysym. You can also use it to redefine the mousebuttons, using the pointer key-
word. For example, to have the secondand third mousebuttons switch places, you can enter:
lmui@opal % xmodmap -e "pointer = 132"

If you have a large number of keys to remap, you can put the commandsin a file that is read
when your X sessionstarts.For example, you create a file called Xmodmap:
! my .Xmodmap file
remove Lock = Caps_Lock
remove Control = Control_L
keysym Control_L = Caps_Lock
keysym Caps_Lock = Control_L
add Lock = Caps_Lock
add Control = Control_L

These commands effective reverse your Control and CAPSLOCK keys. (Control and CAPS
LOCK are "switched" on PC and Macintosh keyboards, which can be exceedingly frustrat-
ing.) This file can then be read automatically in a X startup script:

xset b 10 100 10
xrdb $HOME/.Xdefaults
xmodmap $HOME/.Xmodmap
twm &

One danger of using xmodmap is that anything set with xmodmap might remain in effect after
you have logged out. This isn't a problem if you use the sameX serverevery day, but beware
that if you use a co-worker's X terminal in his absence,he may come back complaining that
you broke his CAPSLOCK key. This might happenif you use xdm, since the serveris not res-
tarted after every X session. On some X terminals, you can fix this problem by toggling
"retain X settings" on the X terminal setupmenu.
The xkeycapsclient, availableon export.lcs.mit.edu,
is a front-endto xmodmap.xkeycaps
has the default keysym mappings for several different types of keyboards. If your keyboard
is supportedby xkeycaps,you can use it to resetyour keysymmappingsto its defaults.
Bewarethat if your keyboardis not identicalto the onexkeycapsthinks you have,you will
quickly regret having done this.

Resources
and KeysymMappings 291
D.2.1 Using xev to Learn Keysym Mappings

The xev client is essential for debugging keysym mappings. When you start up xev, a small
"event window" appears. All events that take place within that window are shown on stan-
dard output. This meansscreenfulsof output, but it also meansthat when you type a key, you
can immediately trace the resulting event. For example, if you need to know what keysym is
sent when you type the Delete key on the keyboard, just run xev and type the Delete key in
the event window. Typical output might be:
Keypress event, serial 13, synthetic NO, window 0x800001,
root Ox8006d, subw 0x800002, time 1762968270, (50,36),
root:(190,176), state 0x0, keycode 27 (keysym Oxffff, Delete),
same_screen YES,
XLookupString gives 1 characters: "A?"

KeyRelease event, serial 15, synthetic NO, window 0x800001,

root Ox8006d, subw 0x800002, time 1762968336, (50,36),
root:(190,176),
state 0x0, keycode 27 (keysym Oxffff, Delete), same_screen YES,
XLookupString gives 1 characters: "A?"

This tells you that the Delete key (keycode 27), interpreted as keysym Oxffff, which is
Delete and character A?. If you do an xmodmap -pk, you should seea line resembling:
27 Oxffff (Delete)

If you redefine the Delete key as the Backspacekey and do the same exercise (run xev and
pressthe Delete key), you should seesomething like:
% xmodmap -e "keysym Delete = Backspace"
% xev

KeyPress event, serial 13, synthetic NO, window 0x800001,

root Ox8006d, subw 0x800002, time 1763440073, (44,39),
root:(240,235),
state 0x0, keycode 27 (keysym Oxff08, Backspace), same_screen
YES,
XLookupString gives 1 characters: "AH"

KeyRelease event, serial 15, synthetic NO, window 0x800001,

root Ox8006d, subw 0x800002, time 1763440139, (44,39),
root:(240,235),
state 0x0, keycode 27 (keysym Oxff08, Backspace), same_screen
YES,
XLookupString gives 1 characters: "AH"

This tells you that now the Delete key (still keycode 27) is being interpreted as hexadecimal
Oxf f 08, keysym Backspace, and generatescharacter "AH." xmodmap -pk should show
you:

27 OxffOS (Backspace)

292 The X WindowSystemAdministrator'sGuide

D.3 Related Documentation

The following X manual pages may be of interest: xrdb, xmodmap, xcalc, xcalc, xprop, xev,
and twm.

For more information, see X Window System User's Guide, by Valerie Quercia and Tim
O'Reilly (O'Reilly & Associates,1990).
"Making Better Use of Resources," by Paul Davey, published in The X Resource, Issue 3,
O'Reilly & Associates,Inc., Summer 1992.

Resourcesand Keysym Mappings

 E

The Components of X Products

This appendix lists the contents of various X distributions.

In This Appendix:
MITX11 Releases 298
OSF/Motif 299
Sun OpenWindows 300
DECWindows 301
AlXWindows 302

Silicon Graphics 302

A Guide to X11 Libraries .. ..303
 The Components of X Products

This appendix provides an overview of some of the X products that are currently available.
We summarizevarious vendors' implementations, and discuss features that may help you to
identify them. The following implementations are covered:
" MIT Release 5

" OSF/Motif GUI

" Sun OpenWindows

" DECWindows

" AlXWindows

" Silicon Graphics

We also include a listing of someof the libraries that you may need in compiling software.
Some of these implementations may overlap and may contain componentsof several other
systems. For example, the Motif Toolkit is included in most current vendor-suppliedinstalla-
tions. Several vendors also offer applications that can switch back and forth between
OSF/Motif and OPEN LOOK "modes."

With a complete distribution, X software is installed in the following directories.

Table E-1. X Distribution Directories

File Description
lusrlbinlXHI X executables,including clients, demos, and the X server.
lusrlliblXllI Server-specific software, including fonts, color data-
bases,and configuration files.
lusr/libl X programming libraries.
lusrlindudelXllI X headerfiles and bitmaps.
lusrlmanl X manpages.
$HOMEI User-specific startup and resourcefiles.

The Components of X Products 297

 Keepin mindthatyourpathnames
maydiffer,butthedirectories
bin,lib, andincludeshould
exist in some form.

The namesof libraries vary dependingon the system-SunOS sharedlibraries have a

.so.versionor .sa.versionextension, while Silicon Graphics shared libraries have a _s exten-
sion.A _p extensionusuallymeansthat thelibrary hasbeen"profiled" for performance
anal-
ysis.An extensionsuchas_GOindicatesit wasbuilt with a specificcompileroption.
The following informationshouldhelpyou determinewhattypeof installationyou currently
have and what you would like to install.

E.1 MITX11 Releases

To the user, Release5 looks very similar to Release4. Most of the new features (such as the
font server, PEX, and the Xcms color system) are more visible to the X programmer and to
the administrator than they are to the user.As in R4, the include files for toolkits and related
files are grouped into subdirectories. (In previous MIT releasesand some vendor implemen-
tations, the include files were in one directory.)

Table E-2. MIT X11R5 Files

File Description
lusrlbinlXUIX A link to a server executable. The server name usually starts
with a capital X. For example, Xsun, Xcfbpmax, and Xsgi are
the namesfor X servers.The X server will be present in com-
plete installations.
/usr/bin/Xll/twm Tab window manager.This is the default window manager in
MIT R4 and R5.

lusrlbinlXlllfs The font server program.

lusrlliblXHIPEXI A directory of files used by PEX, the 3-D extension to XI1.
This directory is new to R5.
lusrlliblXlllXKeysymDB A list of keysyms. This should be installed on any system
using OSF/Motif clients and MIT R5 (A different version of
this will file comes with MIT R5). Most Motif clients will fail
to work properly without this file.
lusrlliblXHIXErrorDB A mapping of X error codesto error messages.
lusrlliblXlllapp-defaultsI A directory of system-widedefault resourcesfor clients.
lusrlliblXlllconfigl A directory of configuration files copied from the sourcebuild
area. These configuration files are used by imake when build-
ing X programsafter the X distribution is installed.
lusr/liblX111fonts! A directory of fonts for the X server.If a local X server is not
present (i.e., if it is a client-only installation), this directory
may be unnecessary.The font server could also read fonts
from this directory over the network for a remote server.
/usr/lib/Xll/fs/ A directoryof font serverconfigurationfiles.

298 X WindowSystemAdministrator'sGuide
 Table E-2. MIT X11R5 Files (continued)

File Description

lusrlliblXlllxdml A directory of files required by the xdm client.

lusrlliblXlllrgbl orrgb* Files that contain the RGB databasefor color names.
lusrllibllibXll.a The main library of X functions (Xlib).
/usr/lib/libXaw.a The Athena Widget library.
/usrllibllibXmu.a The miscellaneous functions library.
ImrllibllibXt.a The X Toolkit functions library.
lusrlliblliboldX.a The backward compatibility library.
lusrllibllibXdmcp.a The XDMCP library (R4 and R5).
/usr/lib/lib*X*.a Other X libraries (release-dependent).
lusrlincludelXHI A directory of include files for compiling X programs.
lusrlincludelXl II bitmaps! A directory of bitmaps for random X programs.
$HOMEI Xdefaults User-specific resourcesfor X clients.
$HOMEI Xresources User-specific resourcesfor X resources.
SHOME/.twmrc The user-specific startup file for the twm window manager.
$HOMEI .xinitrc The user-specific startup file for starting the X server using
xinit.

$HOMEI .xsession The user-specific startup file for starting the X server using
xdm.

E.2 OSF/Motif

If you administer any systemsthat run OSF/Motif with X, the files shown in Table E-3 should
be present. Of the files listed, XKeysymDB is an important one that is often forgotten with
some Motif installations. This file maps the official OSF names for keysyms-most Motif
programs will complain and generate numerous error messagesif they cannot find this file
when they start up. XKeysymDB is included in the MIT R5 release.
The namesof the OSF/Motif libraries may be slightly different on your system,dependingon
the release of XI1. Early releases of Motif (1.0.A) came with their own version of the X
toolkit library. Most people named this libXtm.a, libMXt.a, or something similar to avoid con-
fusion with the standardMIT libXt.a. If you are compiling a Motif program on one of these
systems,the Motif specific X Toolkit library needs to be linked with:
% cc -o motifthing motifthing.c -iXm -IXtm -1X11

The location of the Motif include files may also vary depending on the implementation. The
default location provided by OSF places them in I usrIinclude, but they may be in
lusrlincludelXl 1 instead. You may want them under lusrlincludelXl 1 in order to keep all X11
files in one place. If so, the alternate location has to be specified with the -/ flag to cc:
% cc -c -I/usr/include/Xll motifthing.c

The Components of X Products 299

 Motif programsincludetheheaderfileswith theMotif subdirectoryprepended:
#include <Xm/Xm.h>

Thecompletepathnameof this file becomes

lusrlincludelXlllXmlXm.h.

Table E-3. Motif Files (Motif 1.1.x)

File Description
lusrlbinlXlllmwm The Motif Window Manager.
lusrlbinlXllluil The UIL (User Interface Language)compiler.
lusrlbinlXlllmre The Motif Resource Editor (this is officially a "demo,"
but it is potentially quite useful-only present in version
1.x).
lusrllibllibMrm.a The Motif resourcemanager library.
lusrllibllibXm.a The Motif toolkit library.
lusrllib/libUil.a The Motif UIL library.
lusrlliblXlllXKeysymDB A databaseof special OSF keysyms for Motif applica-
tions.

lusrlliblXl 1/app-defaults/Mwm System-wide default resourcesfor mwm.

lusrlliblXl llsystem.mwmrc The default startup file for mwm.
lusrlliblXllluidl A directory of compiled UIL files for clients.
lusr/include/Xml A directory of Motif toolkit include files.
lusrlincludelMrml A directory of Motif resourcemanagerinclude files.
lusrlincludeluill A directory of Motif UIL include files.
$HOME/.mwmrc The user-specific startup file for mwm.

E.3 Sun OpenWindows

The OPENLOOK GUI is currently packaged as part of the OpenWindows environment on

Sun systems.OpenWindows is laid out differently from the MIT X installation: all software
is installed under /usr/openwin, as listed in Table E-4.

TableE-4. OpenWindowsFiles (Sun4, SunOS4.1.1)

File Description
bin/openwin Theserverstart-upscript.
bin/ A combinationof X, OpenWindows,
andNeWSclients.
demo/ A combinationof X, OpenWindows,
andNeWSdemoprograms(including
a demoxterm).
etc/ Configuration information for NeWS.
include/ Headerfilesfor X andOpenWindows.

300 X WindowSystemAdministrator's
Guide
 TableE-4. OpenWindowsFiles (Sun4, SunOS 4.1.1) (continued)

File Description

lib/ Server-specific software for OpenWindows.

man/ Man pages for X and OpenWindows. (You may have to do "setenv MAN-
PATH lusrlman:lusrlopenwinlman" for the man command to find them.)

Table E-5 summarizesthe more important OPENLOOK files.

Table E-5. OPEN LOOK Files

File Description
lusrlopenwinlbinlxnews The OpenWindows server.
/usr/openwin/bin/olwm The OPEN LOOK Window Manager.
/usr/openwin/bin/props The resourceeditor (similar to Motif's mre).
/usr/openwin/lib/lib* Programming libraries for OPEN LOOK functions.
/ usr/openwin/lib/openwin-* System-wide default files.
$HOME/.openwin-* Per-userdefault files.

E.4 DECWindows

DECWindows is moving towards a Motif-like environment, but is still different in many

ways. Most of it should be quite familiar to someoneused to a MIT distribution. The MIT-
derived Xll is available as an unsupported subset that can co-exist with the DECWindows
environment.

Table E-6. DECWindows Files (DecStation, Ultrix 4.2)

Files Description
/usr/bin/Xws The DECwindows server.

lusrlbinldxwm The DECwindows window manager.

lusrlbinldxsession The DECwindows sessionmanager.
/usr/bin/Xprompter The login window tool (similar to xdm).
lusrlbinldxuil The DECwindows User Interface Languagecompiler.
lusrlliblXllluidl A directory of compiled UIL files.
lusrlincludelXllI A directory of both of DECwindows and MIT headerfiles.
lusrlindudelmitlXllI A directory of vanilla MIT header files.
lusrllibllibXext.a The DECwindows version of libXext.
lusrllibllibXext-mit.a The vanilla MIT libXext.

The ComponentsofX Products 301

E.5 AlXWindows

AlXWindows
is quitedifferentthantheMIT distribution
andit maytakesomeworkto getit
to look like the MIT environment. The names and options of standard clients have been
changed
fromwhatyouareusedto, andthe layoutof the software
is quitedifferentthan
othervendors'implementations.The currentversionof AIX, 3.2, is alsomissingsomecli-
entsyouwouldexpectwhenusingan MIT distribution.
Thelayoutof librariesandinclude
files is relatively standard.

Table E-7. AlXWindows Files (RS/6000, AIX 3.2)

Files Description
lusrlbinlXHIX The AlXWindows server.

lusr/binlXl 1 lm\vm The Motif window manager.

lusrlbinlXlllxdt The AlXWindows desktop.
lusrlbinlXlliaixterm The AlXWindows version ofxterm.
lusrlbiniinfo The InfoExplorer hypertext X documentation browser.
/usr/include/Xll/*.h AlXWindows header files.
lusr/includelXml*.h Motif 1.x header files.
/usrl include/Mrml*.h
/usrl include! uil/*.h
/usrllibllib*.a Standard XI1 R4 and Motif 1.x libraries.
lusrlliblXUI Standard XI \R4lib files.

lusr/lpplinfolXl 1font si A directory of fonts for the InfoExplorer utility.

E.6 Silicon Graphics

SGI has had a decentNeWS implementation for several years, working together with the SGI
Graphics Library system (GL). X functionality was added over time in a piecemeal fashion.
With the releaseof IRIX 4.0, XI1 is an integral part of the server, and works well along with
GL and NeWS. The clients are based on OSF/Motif, which comes with the OS.

TableE-8. GraphicsX11 Files (Indigo,IRIX 4.0)

Files Description
lusr/binlXll/Xsgi A combinedXll/GL/NeWS server.
/usr/bin/Xll/4Dwm A mwm-like window manager.
lusrlbinlXllltoolchest A "desktop" managerclient.
/usrlliblXHI A directory of XI1 R4 "lib" files.

302 X WindowSystemAdministrator'sGuide
 Table E-8. Graphics X11 Files (Indigo, IRIX 4.0) (continued)

Files Description
/usr/include/Xll/ A directory of both XI1 R4 and Motif 1.1 headerfiles.
lusrllibllib* XI1 R4 and Motif 1.1 libraries.

E.7 A Guide to X11 Libraries

When compiling software, you may suddenly discover that it requires a library you've never
heard of. In your XI1 adventures,you may seereferencesto the following libraries.
Library Description

libXll.a Xlib
HbXaw.a Athena widget set
HbXext.a Extensions to Xlib
libXt.a Toolkit
libXau.a Authorization
libXdmcp.a XDMCP
libXinput.a Input methods
libXmu.a Misc Utilities
liboldX.a Backwards compatibility library for X10
libphigs.a R5 phigs
libXm.a Motif widgets
libUil.a Motif user interface language
libMrm.a Motif resourcemanager
HbXtm.a libMXt.a Namesfor libXt when Motif (1.0.A) required its own version
libMu.a MIT Motif utilities library (sometimes found in software from MIT
Athena project)

libXw.a HP Widgets in R3 and R4 contrib

The Components of X Products 303

 Getting XI1

This appendix lists where you can get the sources and patches to both
Release 4 and Release 5 of X11.

In This Appendix:
Where Can I Get X11R5? 307
Where Can I Get Patches to X11R5? 311
Where Can IGetX11R4? .. ..311
 Getting X11

The information in this chapter is taken from the comp.windows.xFrequently Asked Ques-
tions List. We provide it here for your convenience, but we encourage you to get the latest
version of the FAQ (as describedin Section A.2) for more updated information.

WhereCanlGetX11R5?

Information about MIT's distribution of the sourceson 6250bpi and QIC-24 tape and its dis-
tribution of hardcopy of the documents is available from Software Center, Technology
Licensing Office, MassachusettsInstitute of Technology, 28 Carleton Street, Room E32-300,
Cambridge MA 02142-1324, phone: 617-258-8330.
You will need about 100Mb of disk spaceto hold all of Core and 140MB to hold the Contrib
software donated by individuals and companies.
PLEASE use a site that is close to you in the network.

Note that the RELEASEnotes are generally available separately in the same directory; the
notes list changesfrom previous versions of X and offer a guide to the distribution.

Table F-1. North America Anonymous ftp

State Name Directory Address

California gatekeeper.dec.com publXUIRS 16.1.0.2
California soda.berkeley.edu publXHR5 128.32.131.179
Indiana mordred.cs.purdue.edu publXHIRS 128.10.2.2
Maryland ftp.brl.mil publXHR5 128.63.16.158
(good for MILNET sites)
Massachusetts crl.dec.com publXll/R5 192.58.206.2
Massachusetts export.lcs.mit.edu pubIRS 18.24.0.12
(crl.dec.com is better)
Michigan merit.edu publXllRS 35.1.1.42
Missouri wuarchive.wustl.edu packageslXURS 128.252.135.4
Montana ftp.cs.montana.edu pub/X.VURS 192.31.215.202
New Mexico pprg.eece.unm.edu publdistlXURS 129.24.24.10
New York azure.acsu.bujfalo.edu publXURS 128.205.7.6

Getting X11 307

TableF-1. NorthAmericaAnonymous ftp (continued)

State Name Directory Address

North Carolina cs.duke.edu dist/sourceslXl1R5 128.109.140.1
Ohio ftp.cis.ohio-state.edu publX.VURS 128.146.8.52
Ontario ftp.cs.utoronto.ca pub/XllRS 128.100.1.105
Washington
DC xllr5-a.uu.net X/R5 192.48.96.12
WashingtonDC xllr5-b.uu.net X/R5 137.39.1.12

TableF-2. Europe/MiddleEast/AustraliaAnonymous ftp

Country Name Directory IP Address

Australia munnari.oz.au X.V11/R5 128.250.1.21
Denmark freja.diku.dk publXHR5 129.142.96.1
United Kingdom src.doc.ic.ac.uk graphicslX.VHR5 146.169.3.7
hpb.mcc.ac.uk publXllrS 130.88.200.7
Finland nic.funet.fi pub/Xll/R5 128.214.6.100
France nuri.inria.fr X/X11R5 128.93.1.26
Germany ftp.germany.eu.net publXlllXURS 192.76.144.129
Israel cs.huji.ac.il pub/XllR5 132.65.6.5
Italy ghost.sm.dsi.unimi.it publXURS 149.132.2.1
Netherlands archive.eu.net \vindowslXIR5 192.16.202.1
Norway ugle.unit.no publXHR5 129.241.1.97
Norway nac.no pub/XllR5 129.240.2.40
Switzerland nic.switch.ch softwarelXURS 130.59.1.40

Table F-3. Japan Anonymous ftp

Region Name Directory IP Address

Kanagawa sh.wide.ad.jp X11R5 133.4.11.11
Kwansai ftp.ics.osaka-u.ac.jp X11R5 133.1.12.30
Kyushu wnoc-fuk.wide.ad.jp X11R5 133.4.14.3
TISN utsun.s.u-tokyo.ac.jp X11R5 133.11.11.11
Tokyo kerr.iwanami.co.jp X11R5 133.235.128.1
Tokyo scslwide.sony.co .jp publXHR5 133.138.199.1

308 X WindowSystemAdministrator'sGuide
Table F-4. UUCP

Name Comment Directory

uunet for UUNET customers 'IXIR5
decwrl existing neighbors only -IpublXllIRS
osu-cis (not online until early September) '/X.V11R5
WJanon (host: watjo.swp.wj.com) -IXIX11R5I
Modem: Telebit TB2500 (PEP, V.32, etc)
Systems or L.sys suggested/approximate
entry:
WJanon Any ACU 19200
1-408-435-0240""\login: WJanon
utai existing neighbors only -Iftplpub/XllRS
hp4nl Netherlands only ~uucp/pub/windows/X/R5

Table F-5. Other File Transfer Methods

Method Region Comments

NFS Missouri wuar chive .wustl.edu
I archive!packagesIX 11R5
128.252.135.4
mount point: Iarchive
AFS Pennsylvania lafs/grand.central.org/pub/Xl 1R5
NIFTP United Kingdom uk.ac.ic.doc.src
(hhcp, cpf, fcp, <X.V11R5>
00000510200001

user "guest"
anon FTAM United Kingdom 000005102000(Janet)
X.V11R5
146.169.3.7 (Internet)
204334504108 (IXI)
ACSNet Australia munnari.oz (fetchfile)
X.V11/R5
Please fetch only one file at a time, after check-
ing that a copy is not available at a closer site.

[9/2/91; updated forcontrib 10/91]

Anyone in Europe can get a copy of the MIT X.V11R5 distribution, including the core and
contributed software and all official patches,free of charge. The only requirement is to agree
to return the tapes, or equivalent new tapes. Only QIC and TK format cartridges can be pro-
vided. Contact: Jamie Watson, Adasoft AG, Nesslerenweg 104, 3084 Wabern, Switzerland.
Tel: +41 31 961.35.70or +41 62 61.41.21; Fax: +41 62 61.41.30;[email protected].

Getting X11 309

UK sitescanobtainXI1 throughtheUKUUGSoftwareDistributionService,from theDepart-
mentof Computing,ImperialCollege,London,in severaltapeformats.Youmayalsoobtain
the source via Janet (and therefore PSS) using Niftp (Host: uk.ac.ic.doc.src Name: guest
Password: your_email_address).
Queries should be directed to Lee McLoughlin,
071-589-5111#5037,or to [email protected] [email protected] (senda Sub-
ject line of "wanted".Also offeredarecopiesof comp.sources.x,
theexport.lcs.mit.edu
con-
trib and doc areasand most other announcedfreely distributable packages.
XI1R5 and XI1R4 sourcealong with XI1R5 contrib code, prebuilt X binaries for major plat-
forms, and source code examples from O'Reilly's books is available on an ISO-9660-format
CD-ROM from O'Reilly & Associates,[as of 3/92].
X11R5 source is available on ISO-9660-format CD-ROM for members of the Japan Unix
Society from Hiroaki Obata, [email protected].

XI1R5 source along with GNU source, the comp.sources.xarchives, and SPARCbinaries is
available on an ISO-9660-format CD-ROM from PDQ Software, 510-947-5996 (or Robert A.
Bruce, [email protected]).

XI1R5 sourceis available from Automata Design Associates,+1 215-646-4894.

Various users' groups (e.g., SUG) offer X sourcescheaply, typically on CD-ROM.
Source for the Andrew User Interface System5.1 and binaries for common systemsare avail-
able on CD-ROM. Information: [email protected], 412-268-6710, fax
412-621-8081.

Binaries for XI1R5, with shared libXl 1 and libXmu, for A/UX 2.0.1 are now available from
wuarchive.wustl.edu:/archive/systems/aux/XHR5. Patches for X11R5 compiled with gcc
(but not shared libraries) are also available. [John L. Coolidge ([email protected],
10/91)]

Binaries by Rich Kaul ([email protected])for the Sun386i running SunOS 4.0.2

are available on dsinc.dsi.com(please only after-hours USA EST).
Binaries for the Sun386i are available from compaq.com (131.168.249.254) in
pub/sun-386i/sourcesand from vernam.cs.uwm.edu(129.89.9.117).
A binary tree for the Next by Douglas Scott ([email protected]) is on fox-
trot.ccmrc.ucsb.edu;it is missing the server,though.
Binaries for the Sun386i are in vernam.cs.uwm.edu:/sun386i.

Binaries for the HP-PA are on hpcvaaz.cv.hp.com(15.255.72.15).

Also, Binariesareavailablefrom Unipalm(+44 954 211797,[email protected]),
proba-
bly for the Sun platforms.

310 x WindowSystemAdministrator's
Guide
F.2 Where Can I Get Patches to X11R5?

The releaseof new public patchesby the MIT X Consortium is announced in the comp.win-
dows, x.announce newsgroup.

Patchesthemselves are available via ftp from export and from other sites from which XI1 is
available. They are now also distributed through the newsgroup comp.sources.x.Somesource
re-sellers may be including patchesin their sourcedistributions of XI1.
People without ftp accesscan use the xstuff mail server. It now has 17 patchesfor X11R5
[8/92]. Sendto [email protected] the Subject line:
send fixes #

where # is the name of the patch and is usually just the number of the patch.
Here are a few complications:
1. Fix 5 is in four parts; you needto request"5a", "5b", "5c" and "5d" separately
2. The file sunGX.uu, which was part of an earlier patch, was re-releasedwith patch 7
3. Fix 8 is in two parts: "8a" and "8b"
4. Fix 13is in three parts: "13a", "13b", and "13c"
5. Fix 16is in two parts: "16a" and "16b"

F.3 WhereCanlGetX11R4?

Integrated Computer Solutions, Inc., ships X11R4 on half-inch, quarter-inch, and TK50 for-
mats. Call 617-621-0060 for ordering information.
The Free Software Foundation (617-876-3296) sells X11R4 on half-inch tapes and on
QIC-24 cartridges.
Yaser Doleh ([email protected]; P.O. Box 1301, Kent, OH 44240) is making XI1R4
available on HP format tapes, 16 track, and Sun cartridges. [2/90]
European sites can obtain a free XI1R4 distribution from JamieWatson, who may be reached
at chx400!pan!jw or [email protected]. [10/90]
Non StandardLogics (+33 (1) 43 36 77 50; [email protected])makes source available.
IXI Limited (+44 223 462 131) is selling XI1R4 sourceon quarter-inch cartridge formats and
on 5.25" and 3.5" floppy, with other formats available on request. [IXI, 2/90]
Virtual Technologies (703-430-9247) provides the entire X11R4 compressedsource release
on a single QIC-24 quarter-inch cartridge and also on 1.2 meg or 1.44 meg floppies upon
request. [Conor Cahill ([email protected]) 2/90]
Young Minds (714-335-1350) makes the R4 and GNU distributions available on a full-text-
indexed CD-ROM.

GettingX11 311
[Note that somedistributions aremedia-only and do not include docs.]
XI1R4 is ftp-able from export.lcs.mit.edu; thesesites are preferable, and are more direct:
Location Name Address Directory
(1) West USA gatekeeper.dec.com 16.1.0.2 publXHIR4
Central USA mordred.cs.purdue.edu 128.10.2.2 publXUIR4
(2) Central USA giza.cis.ohio-state.edu 128.146.8.61 pub/X.VHR4
Southeast USA uunet.uu.net 192.48.96.2 XIR4

(3) NortheastUSA crl.dec.com 192.58.206.2 publXlllR4

(4) UK Janet src.doc.ic.ac.uk 129.31.81.36 X.V11R4
UK niftp uk.ac.ic.doc.src <XV11R4>
(5) Australia munnari.oz.au 128.250.1.21 X.V11IR4

The giza.cis.ohio-state.edusite, in particular, is known to have much of the contrib stuff that
can be found on export.
The releaseis available to DEC Easynet sites as CRL::"/pub/Xl 1/R4".
Sites in Australia may contact this address:ftp.Adelaide.EDU.AU [129.127.40.3] and check
the directory pub/X/R4. The machine shadows export and archives comp.sources.x. (Mark
Prior, [email protected], 5/90)

Note: a much more complete list is distributed regularly by Dan Heller ([email protected]) as
part of the introductory postings to comp.sources.x.
A set of X11R4 binaries built by Tom Roell ([email protected]) for the
386/ix will available from export.lcs.mit.eduin /contrib and in /pub/i386/XHR4 from
131.159.8.35in Europe. Stephen Hite ([email protected]) can also distribute to folks
without ftp facilities via disks sentSASE;contacthim for USmail and shippingdetails.
[12/90] In addition,the binariesare availablevia uucp from szebra[1-408-739-1520,
TB+
(PEP); ogin:nuucp sword:nuucp] in /usr2/xbbs/bbs/x. In addition, the source is on zok in /usr-
X/i386.R4server/.
[2/91] In addition,if you arein theU.S.,the latestSVR4binary(April 15),
patches,and fonts are available on piggy.ucsb.edu(128.111.72.50)in the directory
/pub/X386,
samefilenames
asabove.(Please
useafter6pmPacific,asthesearelargefiles.)
[5/91]

A set of HP 9000/800binariesis availableon hpcvaaz.cv.hp.com

(15.255.72.15)
as
"ftp/pub/MitXl!R4/libs.x800.Z.[2/91]
A setof X11R4binariesfor theNeXT2.x havebeenmadeavailableby HowieKayeon
cunixf.cc.columbia.edu

A setof binaries
by JohnCoolidge([email protected]) for theMacrunningA/UX2.0is
available
fromwuarchive.wustl.edu
in thefile (/archive/systems/aux/XHR4/Xupdate2.tar.Z)
Also in XI lR4/diffs is a setof patchesfor makingXI1R4 with sharedlibrarieswith mkshlib.
A complete
distribution
of SCOX11R4binaries
by BaruchCochavy
([email protected]
ion.ac.il)
canbefoundonuunet.
Theserver
isRoell'sX386Lib, compiled
forET4000
based
SVGA boards.

312 X Window
System
Administrator's
Guide
 G

Error Messages

This appendix lists error messages that you might get when running X cli-
ents. We not only list errors from X programs but also UNIX errors that you
often encounter when running or compiling X programs.

In This Appendix:
X Errors 315
UNIX Errors 318

Compilation Errors 320

 G
Error Messages

This appendix lists error messagesthat you might get when running X clients. This appendix
is broken up into the following categories:
X Errors Errors that you may get from X clients.
UNIX Errors Errors that you may get when running X clients, but which reflect
problems more closely associatedwith UNIX.
Compilation Errors Errors that you may get when compiling programsunder UNIX.

G.1 X Errors

Can't Open display

or

Unable to open display

There is a problem with the DISPLAY variable or with the display specified using the -dis-
play option. The DISPLAY variable may not be set properly, or the specified host may be
unknown. The host may also not have accessto the specified display. Correct the setting of
the DISPLAY variable, or extend server accessas appropriate using either xhost orxauth. See
Section 2.3.1 for more information on setting the DISPLAY variable, or Chapter 4 for infor-
mation on server access control.

(This particular error is actually generated by the application, so it may not be worded
exactly like this. "Can't open display" is the wording generatedby Xt-based applications.)

Unknown preprocessor directive

or

n: undefined control

You might get this error from xrdb if you used the "#" character to comment out a line in a
resource file. For a resource file, replace the "#" with a "!", or use a dummy resourceentry.
See Section D.I.3 for more information.

Error Messages 315

X Error of failed request:BadValue(integerparameterout of rangefor operation)
Major opcode of failed request: 51 (X SetFontPath)
Minor opcode of failed request: 0
Resource id in failed request: 0x4
Serial number of failed request: 4
Current serial number in output stream: 6

Error from thexsetclient whenyoutry to add a new elementto thefont path.This couldbe
becauseof any of the following problems:
" The new font directorydoesn'texist or it not readableby the server. This could be a
filesystem permissionsproblem or an NFS accessproblem.
" Thefonts.dir file could be missing or damaged.
" If you try to add a font serverto thefont path,the font servercouldhavediedor maynot
be running on the specified port number.

See Section 5.1.4 for more information.

failed to set default font path '/usr/lib X11/fonts misc/,/usr/lib/X11/fonts/Speedo/,

/usr/lib/X11/fonts/75dpi/,/usr/lib/X11/fonts/100dpi/'
Fatal server error:

could not open default font 'fixed'

You may get this error when starting the X server. One or more of the default font directories
is missing, unreadableor has something wrong with the fonts.dir file. Check that each of
thosedirectories is readable. You might also get this error if a font server is part of the font
path and is not currently running. You can override the default font path using the -fp option
to the X server command; see Section 5.1.4 for more information.

Warning: Cannot convert string " ... "to type FontStruct

You cannot access the specified font, either because it doesn't exist or because the server
does not have read access to it. See Section 5.1.4 for more information.

Warning: Color name ... is not defined in server database

You have specified a color to an application that is not defined. Either the color name was
misspelt,or it wasnot properlyinstalledfor theserver.SeeChapter6 for moreinformation.

X Toolkit Warning: Cannot allocate colormap entry for White

X Toolkit Warning: Cannot allocate colormap entry for Black
X Toolkit Warning: Cannot allocate colormap entry for white
X Toolkit Warning: Cannot allocate colormap entry for black
Your color databaseis corrupted. You need to recreatethe color database;see Section 6.1.3
for more information.

316 The X WindowSystemAdministrator's Guide

Xlib: connection to "hostname:Q.Q" refused by server
Xlib: Client is not authorized to connect to server
Error: Can't Open display

The client does not have permission to connect to the specified server. Either host-basedor
user-based access control is in effect. You need to add the host to the xhost list for that
server, or you need to copy the code to your .Xauthority file on this host using xauth, or (if
you are using SUN-DES-1security) you need to be added to the xhost list on the server. See
Chapter4 for more information.

Warning: Widget class nnn version mismatch (recompilation needed):

widget 11004 vs. intrinsics 11003.

You are probably mixing MIT clients with Sun OpenWindows libraries or vice versa. You
should specify the right libraries for the client:
% (setenv LD_LIBRARY_PATH /usr/openwin/lib; OW-client)
% (setenv LD_LIBRARY_PATH /usr/lib; MIT-client)

Fatal server bug! no screens found.

You might get this error when starting a Sun X server, where you can use the -dev option to
specify a different device (such as -dev IdevlcgfourO -dev Idevlbwtwol). A device listed
with the -dev option is incorrect, or the device may be missing from /dev.

mwm: Invalid accelerator specification on line n of specification string

mwm: Invalid accelerator specification on line m of configuration file

The Motif Window Manager mwm uses function keys which your server does not have
defined. You should define the function key using xmodmap, or alter your .mwmrc to use a
different key.

unknown keysym osfDown ...

Motif-based applications (such as mwm) require the proper installation of the file
lusrlliblXlllXKeysymDB. This file comes with most Motif distributions and is also presentin
X11R5.

Error Binding TCP socket

You may get this error when starting the X server on a workstation display. The server will
try to create the socket in ItmplXll-unixl'. If the limp directory is not writable, the X server
will fail.

Error Messages 317

 XIO: fatal IO error 32 ...
The connection was probably broken by a ...
Older X Toolkit clientsdon't handleorderly shutdownwell. Modemwindow managers
use
the ICCCMto terminate a client; older versions of clients will complain when they are killed
by thewindowmanager,
insteadof goingawayquietlylike theyaresupposed
to.

G.2 UNIX Errors

Permission denied.

You may get this error if you're running an X client from a remote host. This is a rsh error,
not an X error: the local host needs to be in the remote host's hosts.equiv, or in the user's
.rhosts file. See Section 2.3.4 for more information.

hostname: hostname: No such file or directory

or

hostname: hostname: cannot open

You may get this error if you're running an X client from a remote host. You are probably
trying to use rsh, but are running the restricted shell insteadof the remote shell. You should
changeyour path to get the right one. See Section2.3.4.1 for more information.

stty: Operation not supported on socket

You may get this error if you're running an X client from a remote host. If you are using rsh,
the .cshrc file on the remote host probably has an interactive command in it (such as stty).

Type xterm unknown

or

emacs: Terminal type xterm is not defined.

or

xterm: Unknown terminal type

I don't know what kind of terminal you are on - all I have is 'xterm'.

The xterm entry is missing from the termcap or terminfo database.You need to install the
entry; seeSection 8.4.4 for more information.

Not login shell.

You might get this error in an xterm window whenyou try to run logout insteadof exit to
closethewindow, xtermdoesnot openlogin shellsby default.To startxtermasa login shell,
use the -Is option to xterm, or set the xterm*loginShell resource to true. To exit a
shellthat isn't a login shell,useexit insteadof logout.

318 TheX WindowSystemAdministrator's

Guide
There are stopped jobs

You are trying to exit a shell without properly exiting or killing all jobs started in that shell.
You should properly quit the jobs before exiting the shell-use the jobs command for a list
of your stoppedjobs.

command: Command not found.

You may get this error if the requestedcommand isn't in your search path, or if it doesn't
exist. Make sure the command is installed and make sure its path is in your searchpath.

command-Permission denied.

You may get this error if the command is in your searchpath but you don't have execute per-
mission for it.

Host is unreachable
no network route is known to that host

You may get this error when there is a routing problem-the gateway is probably down or
misconfigured.

Connection timed out

You tried to connect to a host that is currently down or otherwise unreachable.

Id.so: libX11.S0.4: not found

You might get this messageif you are running SunOS. Either the sharedlibrary cacheis out
of date, the shared library is missing, or the shared library is not in your LD_LIBRARY_PATH.
You should either set the LD_LIBRARY_PATHenvironment variable to the appropriate value,
run Idconfig to update the library cache, or install the missing library. See Section 8.4.2 for
more information.

No more processes

Your host has reached its process limit. You should increasethe number of processesthat the
host can handle at once; see Section 7.7.1 for more information.

Sorry, pid ... was killed due to lack of swap space

Your host has run out of swap space. You should increase the amount swap spaceon your
host; see Section 7.7.3 for more information.

Error Messages 319

G.3 Compilation Errors

reversed(or previouslyapplied)patch detected!Assume-R [y]

Youmight get this error whenrunningthepatch program.Youshouldabortpatch, sinceyou
are probably applying the patchesin the wrong order.

Id: /lib/libX11.a:warning:table of contentsfor archive is out of date; rerun ranlib(1)

Youmight,getthis error whencompilingsources.Themodificationdateon the library file is
different thanthe storedtime stampin the library-probably from copyingthe library from
another location. Run ranlib -t on the libraries.

make: Fatal error in reader: Makefile, line n: Unexpected end of line seen

Some cpp programsconvert tabs to spaces.Tabs are required by make. If you get this error,
you might have to install another version of cpp; seeSection 8.7.3.4for more information.

Unknown preprocessor directive

or

n: undefined control

You might get this error from imake or xmkmf if a line is commentedin your Imakefile using
a hash sign (#) instead of using the XCOMM command. See Section 8.7.3.1 for more infor-
mation.

Id: Undefined symbol

You are trying to compile a program which usesa library that is missing. See Section 8.8.1.2
for more information.

filename: n: Can't find include file ...

Youaretrying to compilea programwhich includesa headerfile that is missing.SeeSection

8.8.1.1 for more information.

320 TheX WindowSystemAdministrator's

Guide
 Index

::(double colon), in Makefiles, Adobe fonts, 101

225 converting to F3, 113
: (colon), in resourcedefinitions, converting to XI 1/NeWS for-
281 mat, 126
! (exclamation point), in resource AIX, 188
definitions, 282 chown command, 211
in resourcefiles, 287 installing font server on, 133
in Xaccess file, 56 installing xdm on, 70
# (hash sign), 219 AlXWindows, 8, 187
in resourcedefinitions, 287 components of, 302
in RGB specification, 145 fonts; example, 121-122
used to comment out lines, 315 InfoExplorer client, 117
% (percent sign), in Xaccessfile, aliases
59 for fonts, 108-109, 114;
* (asterisk), and specifying fonts, DECWindows, 119;
108 OpenWindows, 124
in resource definitions, 281-283 for hostnames, 138
in Xaccess file, 56-57 for RGB color, 145
/**/ (null comment), 219 for Xcms color, 149
? (question mark), in resource alternate-servers (font server),
definitions, 283 129,134
@@ (imake syntax), 220 anonymous ftp, (see ftp com-
\ (backslash), in resourcedefini- mand)
tions, 282 AnswerBook, 186
app-defaults directory, (see
application defaults)
Apple Macintosh computers,
Communications Toolbox,
access control 275-277
server, 73-93; MacTCP, 275-277
host-based (see host-based UNIX and, 275
access control),; X clients and, 271,275
reasons for, 73; X servers and, 271,275
user-based(see user-based application defaults, 258, 285
access control),; ar command, 199, 207
X terminals, 83, 175; arch command, 192
xauth vs. xhost, 82-83 Archie, 248-250
xdm, 47 help command, 249
.ad files, (see application defaults) mail server, 250
additional style, font name field, prog command, 249
102 servers, 248

Index 321
Archie(cont'd) SunOS,
69,131
setsearchcommand,249 SystemV,132-133
xarchieclient,251-259 Ultrix, 70
archie command,248 booting,X terminals,167-168
arp command, 169 BOOTP, 163,165-166
arp tables,169 X terminals
and,164
Athenawidgets,7 bootpddaemon,165
autologoutfeature,26 errors,169
averagewidth, font namefield, BootstrapProtocol,(seeBOOTP)
102 BOOTSTRAPCFLAGS,228
broadcast address, 168,173
broadcast queries, 55-57
B and subnet, 173
X terminals and, 173
backgroundcolor, 281 bug reports, 194
specifying,23, 144 build errors, memoryfault, 199
backgroundprocesses, 26 build flags,205-210
backingstore, 161-162 BuildServer,210
Backspacecharacter,mappingto DefaultCCOptions, 210-211
Delete, 290 DefaultFontPath, 117,212
be command, 81, 146, 243 ExpandManNames, 207
BDF format, 111, 125, 129 HasLargeTmp, 199,207
converting DECWindows fonts HasSecureRPC,86
to, 120 HasXdmAuth, 84, 207
converting SNF to, 112 InstallCmd, 211
converting to PCF, 112, 138 InstallFSConfig, 128,207
converting to SNF, 112, 114 InstallLibManPages, 207
converting to XI 1/NeWS for- InstallXdmConfig, 206
mats, 112 InstallXinitConfig, 206
getting from font server, 112, ProjectRoot, 207-208
136 StripInstalledPrograms,207
getting from X server, 112 building X, 185-230
.bdffiles, 111 configuration flags, 205-210
bdftohds command, 171 disk space, 191, 198-200
bdftopcf command, 112 fixes, 186
bdftosnf command, 112, 125, 170 from MIT sources, 185-186
-t option, 114 from source code, 188-189
Berkeley Internet Name Domain, issues,185-190
(see DNS) link trees, 196-197
-bg option, 144,23 NFS-mounted systems,201-203
bigendian, 111, 170 patches, 194-196
binaries,stripping,207 preparation,191-197
BIND, (seeDNS) trouble-free example, 197-198
BITFTP, 237 with imake, 216-225
bitmap, fonts,110 (seealsoinstallingX.)
Bitmap Distribution Format,(see BuildServer build flag, 210
BDF format) byte order, 111, 170
BITNET, 237
bits per pixel, 159
Bitstream fonts, 101
bldfamily command, 107, 126
boot files, AIX, 70, 133
IRIX, 70, 132-133

322 X WindowSystemAdministrator'sGuide
 -name, 283-284;
-rv, 23;
C compiler, (see cc) -server (for font server cli-
C preprocessor, (see cpp) ents), 134;
.calOO files, 153 -xrm,286
cache-size (font server), 128 crtca, 153
CAPSLOCK key, 159 customizing, 20
disabling, 290 DOS-based,272
switching with Control, 291 dxcalendar, 117
cat, Bill, 73 fsinfo, 134
catalogue (font server), 129, 136 fslsfonts, 135
catalogue-list (font server), 129, getbdf, 112
136 InfoExplorer, 117, 121
cc, debugging, 199 Macintosh computers and, 271,
-E flag, 228 275
-g flag, 199 mre, 145-146
-Oflag, 198 props, 145-146
optimization, 198 public domain, 247-268;
-temp= flag, 200 compiling, 255-268;
-v flag, 228 patching, 259-264
.cf files, 222 remote; setting DISPLAY for,
character cell fonts, 102-103 36;
character set, font name field, 102 starting, 34-36
chkconfig command, 133 resize, 31-33
chkey command. 86-87 resources,6
error messages,93 running locally on X terminals,
chmod command, 97 161
chooser client, 53, 55, 57-59 xarchie, 248,251-259
indirect queries and, 57 xcalc, 14
resources, 57, 60 xclock, 14, 16
uses for, 59 xcmsdb, 152-153
chown command, 96 xcoloredit, 145-146
AIX.211 xcolors, 144
-R flag, 202 xconsole, 26, 62
recursive, 202 xdpyinfo, 158
chroot command, 167, 171 xdvi, 115
CIE, 147 xev, 291-293
class names, 283-284 xfd, 103, 108, 115
clean, make target, 224 xfontsel, 20, 104
client-limit (font server), 129, 135 xhost, 28, 35-36, 74-77, 93;
client-only distribution, 189 SUN-DES-1and, 85, 88-90
clients, 3, 13 xinit, 81-82
application defaults, 285 xkeycaps, 264-268, 291
chooser,55, 57-59 xloadimage, 96
cm, 118; xlsfonts, 20, 103, 108
font problems, 123-125 xmessage,33
command-line options, 20-23; xmodmap, 264, 290-293
-bg,23; xpostit, 14, 249
-display, 27-29, 36; xrdb, 24-25,60-61,64,285,
-fg, 23; 287-288
-fn,20, 103; xrolodex, 247
-geometry, 20-22; xrsh, 79
-iconic, 26; xsccd, 153

Index 323
clients (cont'd) xtici, 150
xset,105-106,114-116,124, color database,alternates,147
137 example, 151
xsetroot,25 fixing, 147
xterm,14, 16,93-94,106,144 RGB,146
xtex, 115-117 Xcms, 148-150
xtici, 150-151 XCMSDB, 149
xtrek, 138 color editors, 150-151
xwebster, 259-264 color guns, 143
(see also commercial clients.) color monitors, 143
clone-self (font server), 129, 135 color spaces, 147-148,150
cm client, 118 listing of, 148
font problems, 123-125 colorimeters, 153
CMW (Compartmented Mode commands, ar, 199
Workstations), 98 arch, 192
col command, 242 archie, 248
color, 143-153 arp, 169
aliases, 145 be, 81, 146,243
defining resourcesfor, 145 bdftohds, 171
defining; RGB system, bdftopcf, 112
146-147; bdftosnf, 112, 114,125,170
Xcms, 150-151 bldfamily, 107, 126
device-independent;(see Xcms) chkconfig, 133
editors, 145-146 chkey, 86-87, 93
getting list of, 23 chmod, 97
hexadecimal color values, 145; chown, 96
converting to decimal, 146 chroot, 167, 171
listing, 144 col, 242
monitors, 158 compress,112
RGB system, 143-147; convertfont, 112, 125-126
color names, 144-145; cpp,216-218
defining colors, 146-147; crypt, 86
fixing corrupted database, date,81
147; dmesg, 193
hexadecimalcolor values, domainname,85
148 dxfc, 112
specifying,23 exportfs,172,201,239
Xcms, 144, 147-153; fstobdf, 112, 136
clientdatabase,
148; ftp, 234-235,251
color names, 148-151; imake, 214
color spaces,147-148,150; jobs,319
databaseexample,151; keylogin,90
DCC, 152-153; ksh, 81
defining colors, 150-151; last, 214
deviceprofiles,152-153; Idconfig,200
measuring colors, 153; Idf, 111
specifying colors, 148; Indir, 197
XCMSDB,149; Ipr,242
Xcms.txtfile, 148-150 mach,192
color clients,mre,145 make,197
props,145 makeafb,113,126
xcoloredit,145 man,213,242
xcolors,144 mkfile, 180

324 X WindowSystemAdministrator's
Guide
commands (cont'd) /**/ (null comment), 219
mkfontdir, 107, 114, 116, 139; in font server configuration file,
fonts.scale, 107 128
newkey, 86-87 in imake files, 219
nm, 226 in resource definitions, 282, 287
nroff, 242 in Xservers file, 55
nslookup, 241 XCOMM, 220
openwin, 37 commercial clients, FrameMaker,
patch, 195, 238 65,159
perl, 81 zmail, 33
pstat, 180 Communications Toolbox (Mac-
ranlib, 199 intosh computers), 276-277
rexec, 173 Compatlist file, 109, 126
rgb, 146 compiling sources, 255-268
rlogin, 34 porting hints, 226-230
rsh, 35-36,79, 81 compress command, 112
screendump,96 compressed files, 236, 238, 242
screenload, 96 fonts and, 107, 112-113
setenv,27-28, 30, 134, 149, CompuServe, 235
151, 164, 199,204,211,213, comp.windows.x, 157, 187, 189,
317 233,250
showrgb, 23, 144 FAQ, 234-237, 250
snftobdf, 112 config file (font server), 128-130,
startx, 37-38 139
strings, 192, 229 configuration files, app-defaults
swapon, 180-181 files, 258
tail, 197 .cshrc, 29-30, 33-34, 36
tar, 238, 252 /etc/hosts.equiv,81;
tbl, 242 Secure RFC and, 86, 90
telnet, 164,248 /etc/syslog.conf, 169
trace, 286 /etc/Xn.hosts, 74-75, 82
truss, 286 for font server, 128-131
tset, 31 imake, 222
uname, 192 .login, 33-34
uncompress,238, 242 on remote system, 35-36
unshar,262 .profile, 29-30, 36
uudecode, 195, 236,238 .rhosts, 35,81;
uuencode, 195, 238 SecureRFC and, 86, 90
wait, 26 shell environment, 27-36
X, 16,38,53 startup script, 25-26
xauth, 36, 79-83, 93; syslog, 169
SUN-DES-1and, 89; system.twmrc, 18
using with xinit, 81-82 twm, 15, 18-19
xinit, 16,25,37-38 .twmrc, 15, 19
xmkmf, 214-215, 256, 266 user environment, 14
xrsh, 36, 79 X session, 14
ypbind, 87 X terminals, 161, 175-178
ypmatch, 85-86, 240 .Xdefaults, 286-287
ypwhich, 86, 240 .Xdefaults-hostname, 285
zcat, 238, 242, 252 xdm, 46-66;
comments,! (exclamation point), installing, 206;
282 rereading,52, 55, 59, 67-68;
# (hash sign), 128,219 Xaccess,55-59, 164, 174;

Index 325
configuration
files,xdm(cont'd) inetd,88,167-168;
xdm-config,51-52,78,84, errors,169
95; keyserv,93
Xresources, 60-62; named,241
Xservers,48, 53-55,65,174; rarpd,165
Xsession,63-65 rpc.ypupdated,
87
xinit; installing,206 syslog,129-130,169
.xinitrc,25-26,37-38,90 tftpd,167;
.xinitrc vs. .xsession,39 errors, 169
.Xmodmap,291 xdm;(seexdm)
.Xresources,15,24-25,286 Data Encryption Standard, SUN-
.xserverrc, 38, 82 DES-1,84
.xsession, 14, 25-26, 37 XDM-AUTHORIZATION-1,83
console,security,94-96 supportfor, 86
console windows, 94-96 database, (see color database)
xdm and, 95-96 date command, 81
contrib/, 191 dbm format, 146
controlling process, 26 DCC, 152-153
conversion .dec files, 153
fonts, 112-113; Dead Meat, 138
OpenWindows, 125-126 decipoints, 129
convertfont command, 112, 125 DECnet, 162
-b flag, 126 connecting via, 28
-d flag, 125 font serverand, 136
-sflag, 125 DECWindows, 8, 187
-xflag, 125 components of, 301-302
core, 191 dxcalendar client, 117
Courier, 101 fonts, 111-112, 117-121
cpp, 216-218 DefaultCCOptions build flag,
comments in, 219, 315 210-211
#define command, 218 DefaultFontPath build flag, 117,
errors, 315 212
#ifdef command, 218 default-point-size (font server),
#ifhdef command, 218 129
macro concatenation and, 221 default-resolution (font server),
resource files and, 287 129
standaloneexecution, 228 #define command (cpp), 218
symbols; searching for, 228 delegates, 129
-v flag, 228 depend, make target, 215, 224
cron daemon, 97 depth, 159,161
crtca client, 153 DES, 98, 207
crypt command, 86 (see Data Encryption Standard)
.cshrcfile, 29, 33-34,36 Desqview/X,271-272
CTRL key, 159 /dev/console, 95
/dev/fb, 96-97
Device Color Characterization,
D (seeDCC)
device profiles, Xcms, 152-153
daemons,bootpd,165 device-independent
color, (see
bootp; errors, 169 Xcms)
cron,97 direct queries,55-57
fs; (see font server)
ftpd, 234

326 X WindowSystemAdministrator'sGuide
 X terminals and, 173 TERM, 31
direct queries (cont'd) TERMCAP,32
disk space, X installation and, TMPDIR, 199
191, 198-200 XAPPLRESDIR, 258, 286
X terminals and, 170-171 XCMSDB, 149, 151
diskless workstations, 162 XENVIRONMENT, 258, 285
fonts for, 127 XFILESEARCHPATH, 286
display, problems with, 315, 317 XRSH_AUTH_TYPE, 79
display classes,52, 55, 65-66 XUSERFILESEARCHPATH, 286
example, 65-66 error messages,315-320
finding, 65 auth_create:Bad file number,
DISPLAY environment variable, 93
164 Binding TCP socket: Address
name server problems, 28 already in use, 131
problems with, 28-29, 315 Cannot establish any listening
setting, 27-29; sockets, 131
remote clients, 34, 36 cannot open, 35
using IP address, 28 can't communicate with ypserv,
-display option, 36 93
problems with, 315 Can't find include file, 320
distfile, (see rdist program) Can't lock authorization file, 64
dmesg command, 193 Can't Open display, 36, 315,
DNS, adding a hostname, 240-241 317
and nslookup, 241 Can't open error file
testing, 241 /usr/lib/Xll/fs/fs-errors, 135
documentation, printing, 242-243 cat: ./Compat.list: No such file
Domain Name Service, (see DNS) or directory, 126
domainname command, 85 Client is not authorized to con-
DOS, X clients and, 271 nect to Server, 34, 75
X servers and, 271-275; Color name ... is not defined
advantagesand disadvan- in server database,145
tages,271; Command not found, 29, 319
requirements,272 CONFIG:can't open configura-
dot pitch, 158 tion file ...,135
dxcalendar client, 117 connection refused by server,
dxfc command, 112 34
Connection timed out, 319
Could not set principal's secret
E key, 93
Current serial number in output
editing colors, 145-146 stream, 316
encoding, font name field, 102 Duplicate font names..., 116
encryption codes, server access (Encoding: unknown), 126
control and, 83-84 Fatal server bug! no screens
environment variables, 29 found, 317
DISPLAY, 27-29, 164 Fatal server error!, 131
FONTS ERVER, 134 Host is unreachable, 319
LD_LIBRARY_PATH,30 key containsodd number of or
MANPATH, 213 non-hex characters, 93
OPENWINHOME, 30 Id.so: libXl l.so.4: not found,
PATH, 25, 29 319
SHELL, 33
showing, 27

Index 327
error messages
(cont'd) warning:
tableof contents
for
localresourceallocationfailure, archiveis outof date,rerun
93 ranlib(l), 320
machine
is downornotrunning widget11004vs.intrinsics
rpc.ypupdated,
93 11003,317
Majoropcodeof failedrequest, X Errorof failedrequest:
Bad-
316 Value, 116, 137, 172,316
make: Fatal error in reader: ... X Toolkit Warning: Cannot
Unexpected
endof line seen, allocatecolormapentry,147
320 X Toolkit Warning: Cannot con-
Maybethekeyserveris down?, vertstring ... to type
93 FontList, using fixed font,
Minor opcodeof failedrequest, 117
316 Xlib: Client is not authorized to
mkfontdir; failed to create connectto Server,317
directoryin, 116 Xlib: connectionrefusedby
must be on local machine to add server, 317
or remove hosts, 75 XView warning: Cannot load
mwm; Invalid acceleratorspec- font ...,118
ification on line n of specifi- error-file (font server), 129-130,
cation string, 317 135
No home directory, 64 errors, 169
No more processes,319 compiling, 226
No suchfile or directory, 35 generatedby font server,
Not login shell, 318 129-130, 135
pattern ... unmatched,136 generatedby xdm, 46-47,
Permission denied, 35, 318 49-51,53,63-64
Resourceid in failed request, generatedby .xsessionfiles, 39,
316 47

reversed(or previously applied) linking, 226

patch detected!, 320 undefined functions, 226
Serial numberof failed request, undefined symbols, 226
316 (see also error messages.)
Sorry, pid ... was killed due to /etc/bootptab, 163,165
lack of swap space,319 /etc/ethers, 165, 169,242
Stopped,36 /etc/exports, 172, 201, 239
Terminal type xterm unknown, /etc/fbtab, 97
318 /etc/fstab, 172,180
There are stoppedjobs, 319 /etc/hosts, 239-240
unable to open server, 134-135 /etc/hosts.equiv, 35, 81
unable to update NIS database, SecureRFC and, 86,90
93 /etc/inetd.conf, 167,88
undefinedcontrol,288,320 rereading,168
Undefined symbol, 320 /etc/inittab, 69-70
<unknown addressin family /etc/motd, 33, 168, 192
254>,93 /etc/named.boot. 241
unknownkeysymosfDown, /etc/named.pid,241
317 /etc/passwd,168
Unknownpreprocessordirec- /etc/publickey,85
tive, 288,315,320 /etc/rc.local,69-70,88,131
Warning: Cannot convert string /etc/rc.local file, 53
to typeFontStruct,115,316 /etc/rc.tcpip,70, 133
/etc/resolv.conf, 170

328 X WindowSystemAdministrator'sGuide
/etc/servers, 167 font path, 105-106
/etc/syslog.conf, 130, 169 adding to, 105
/etc/Xn.hosts, 74, 74-75, 82 default, 212
Ethernet, 162 font server, 136-137
hardware addresses,165, 169, listing, 105
242 rehashing, 106, 115, 124
ethers database, 165, 169, 242 font server, 127-139
events, 290 alternate-servers,129, 134
Everything, make target, 225 cache size, 128
ExpandManNames build flag, caching, 128
207 catalogue, 129, 136
exportfs command, 172, 201, 239 catalogue-list, 129, 136
client-limit, 129, 135
clients, 135-136;
-server option, 134
clone-self, 129, 135
F3 fonts, 107,111,125 -configflag, 131, 135
converting to Adobe Bitmap, configuration file; rereading,
113,126 131
.f3b fonts, 111, 113, 125 configuration files, installing,
converting to .afb, 126 207
failsafe session, 50, 61, 63 configuring, 128-130
families, font name field, 101 converting to BDF, 112
Families.list file, 107 debugging, 134-135
rebuilding, 126 default-point-size, 129
FAQ, 233 default-resolution, 129
comp.windows.x, 234-237, 250 error log file, 129-130, 135
.fb fonts, 111, 125 error-file, 129-130, 135
-fg option, 144, 23 errors, 316
File Transfer Protocol, (see ftp example, 138-139
command) flushing font cache, 131
filename length, font files, 107 font formats and, 127
manpage files, 207 font path, 136-137
FILE_NAMES_ALIASES,109 FONTSERVER,134
files, 175 hostname aliases, 138
compressed,112, 236 installing, 130-133
tar, 238 killing, 131
temporary, 199 name syntax, 133-134
uncompressing,252 port, 130
untarring, 252 -port flag, 131
uuencoded,236 resetting, 131
(see also configuration files.) SIGHUPsignal, 131
fix level, 194 SIGTERMsignal, 131
fixed font, 101, 106,108 SIGUSR1signal, 131
fixes, 186 SIGUSR2signal, 131
fromexport.lcs.mit.edu, 194 shutting down, 131
getting with xstuff, 237 starting, 131, 139
(see also patches.) testing, 131
-fn option, 103, 20 trusted-clients, 130, 136
folio fonts, (see F3 fonts) use-syslog, 129-130
font clients, xfd, 103 X terminals and, 160, 163, 171
xfontsel, 20, 104 xdmand, 131, 133
xlsfonts, 20, 103 font server clients, fsinfo, 134

Index 329
 fslsfonts,135 installing,130-133;
fstobdf,112,136 namesyntax,133-134;
font tape,170 port, 130;
fonts, 101-140 starting,131,139;
adding,114-126; testing,131;
multipledirectories,
115 trusted-clients,
130,136;
AlXWindows,121 use-syslog, 129-130
aliases,108-109,114; fonts.dirfile, 106-107,109,
DECWindows, 119; 116;
OpenWindows, 124 creating,107,114,139
average
width, 102 fonts.scale
file, 107-108
BDF format, 111 formats, 111-112;
bitmap,110 convertingbetween,
breakinginto subdirectories, 112-113;
115 font server and, 127
browsing through, 104 foundry, 101
byte order, 111, 170-171 horizontal resolution, 102;
caching,115,128 fontserverand, 129
character set, 102 inability to access,316
CharCell, 102-103 legalities, 113, 136
componentsof font name, 102 linking, 170
converting between formats, listing, 20
112-113, 118 mono-spaced, 103
converting from DECWindows, obtaining list of, 103
118-121 OpenWindows, 107;
DECWindows, 111 Compat.list file, 126;
disk space, 113, 170-171 converting, 125-126;
diskless workstations, 127 example, 123;
displaying characteristicsof, rebuilding Families.list file,
103 126;
downloading; using NFS, 172; Synonyms.list file, 126
using TFTP,171-172 outline, 110
encoding, 102 over the network, 127
F3, 111,125 PCFformat, 111, 170
families, 101 pixel size, 102
filename length restrictions, 107 point size, 102, 129
font conventions, xx PostScript, 111
font path, 105-106; pre-scaledNeWS, 125
default, 212 proportional, 102
font server, 127-139; scalable, 110
alternate-servers,129, 134; selecting with xfontsel, 104
cache size, 128; set width, 102
caching, 128; slant, 101
catalogue, 129, 136; SNFformat, 111, 170
catalogue-list,129,136; spacing,102
client-limit,129,135; specifying,20, 103
clone-self,129,135; Speedo,105,110-111;
default-point-size, 129; fonts.scale and, 107
default-resolution,
129; style,102
error-file,129-130,135; usingin xtermwindows,103
example use, 138-139; vertical resolution, 102;
font path,136-137; font serverand, 129
hostname aliases,138; weight,101

330 X WindowSystemAdministrator's
Guide
fonts (cont'd) H
wildcards, 103, 108
X terminals, 127, 170-172; hardware addresses, 165, 242
installing, 163 HasLargeTmp build flag, 199,
Xll/NeWS, 111, 125 207
fonts.alias Tile, 108-109, 114 HasSecureRPC build flag, 86
adding to, 124 HasXdmAuth build flag, 84, 207
fonts.dir file, 106-107, 109, 116 HDS X terminals, 171
creating, 114, 139 header files, 215
errors, 316 missing, 226
FONTSERVER environment vari- hexadecimal color values, 145
able, 134 converting to decimal, 146
fonts.scale file, 107-108 new format, 148
foreground color, 281 old format, 145
specifying, 23, 144 Xcms and, 148
foreground processes, 26 hexadecimal conversions, 243
foundry, font name field, 101 horizontal resolution, font name
framebuffers, 96-97 field, 102
FrameMaker, 65, 159 host-based access control, 74-77
Frequently Asked Questions /etc/Xn.hosts, 74-75
List, (see FAQ) overriding user-basedaccess
fs daemon, (see font server) control, 82-83, 175
fsinfo client, 134 PC X servers and, 83
-server option, 134 problems with, 76-77
fslsfonts client, 135 X terminals and, 74-76, 79, 83,
fstobdf command, 112, 136 175
FTP, (see ftp command) xhost client, 75-77
ftp command, 234-235, 251 hostname, finding with nslookup,
ftpd daemon, 234 241
ftpmail, 235-236 hosts, accessto font server, 130,
functions, undefined, 226 136
adding to hosts database,
239-241

aliasing, 138
alternate font servers, 129, 134
gateway, problems with, 319 denying accessto; (see host-
generic.cf, 208 basedaccesscontrol)
-geometry option, 20-22 in arp table, 169
getbdf client, 112, 118 increasing number of ptys, 179
getty program, 37, 44 increasing number of users, 179
GiveConsole, 47, 95 increasing processes,178
GrabKeyboard protocol request, increasing swap space, 180-181
93 rebuilding kernel, 179
graphics hardware, finding list of reconfiguring for X terminals,
supported, 193 178-181
grayscale, 65, 158 remote; accessingfonts on, 127
GUIs, 4 Human Designed Systems, (see
and X, 4 HDS X terminals)
Athena widgets, 7
OPEN LOOK, 7
OSF/Motif, 7
gwm window manager, 19

Index 331
 install, make target, 198, 225
InstallCmd build flag, 211
IBM TokenRing,162 InstallFSConfig
buildflag,128,
ibm.cf,211 207
-iconic option,26 installing X, 8, 185-230
iconifyingwindows,19 DEScode,207
#ifdef command(cpp),218 diskspace,191,198-200
#ifndef command(cpp),218 fromMIT sources,185-186
imake, 216-225, 254, 256 in alternatelocation, 207
additional documentationfor, link trees, 196-197
230 manpages,207
.cf files, 222 NFS-mountedsystems, 201-203
commentsin, 219 preparation, 191-197
Concat macro, 222 unprivileged, 201-203
Concat3macro, 222 using rdist, 203
concatenatingmacros,221-222 vendor-supplied, 185-187
configuration files, 222-223 (see also building X.)
flags; BuildServer, 210, 212; InstallLibManPages build flag,
DefaultCCOptions, 210-211; 207
ExpandManNames,207; install.man, make target, 198, 225
HasLargeTmp, 199, 207; in.stall.sh, 211
HasXdmAuth, 207; InstallXdmConfig build flag, 206
InstallCmd,211; InstallXinitConfig build flag, 206
InstallFSConfig, 207; instance names, 283-284
InstallLibManPages,207; Inter-Client Communication
InstallXdmConfig, 206; Conventions, 7
InstallXinitConfig, 206; Interprocess Communication,
ProjectRoot, 198, 207-208; (see IPC)
StripInstalledPrograms,207 IP addresses, 168-169, 242
function of, 217 adding to hosts database,
multi-line macros in, 220 239-240
.rules files, 222 converting hostnamesto, 240
syntax, 219-222 finding with nslookup, 241
.tmpl files, 222 getting with BOOTP,165-166
Uselnstalled flag, 215 getting with RARP, 165
XCOMM command, 220 in display name, 28
xmkmf, 214 name server and, 169
I makefile. 214 X terminals and, 164
editing, 254-255 xhost and, 76
Imake.rules, 223 IPC, 97
Imake.tmpl.223,254 connectingvia, 28
include files, (see headerfiles) IRIX, 185, 187
includes, make target, 215, 224 fonts, 111
indirect queries,55,57-59 installingfont serveron,
chooser client and, 57 132-133
X terminalsand,173 installingxdmon, 70
inetd daemon,88,167 ISO (International Standards
errors,169 Organization),102
rereadinginetd.conf, 88
SIGHUP and, 88, 168
InfoExplorer client, 117
fonts, 121
init program, 44

332 X WindowSystemAdministrator's
Guide
 Indir command, 196-197
local clients, X terminals and, 161
jobs command, 319 log files, font server errors,
129-130, 135
xdm errors, 49-51
K login, problems logging in with
xdm, 49-51
kbdjmode command, 67 remote, 34-36
key symbols, (seekeysyms) login box, configuring, 60-62
keyboards, 159-160 login program, 44
CAPSLOCK key, 159 login shell, 33-34
CTRL key, 159 xterm and, 33
resetting, 67 .login file, 33-34
securing, 93 loose bindings, 52, 282
keylogin command, 90 Ipr command, 242
keymap tables, 290 Lucida, 101
keys, Backspace,290
CAPS LOCK, 290-291
Control, 291 M
Delete, 290
mapping, 290-293 mach command, 192
translation tables and, 288-290 Macintosh computers, Commu-
keyserv daemon, 93 nications Toolbox, 275-277
keysyms, 6, 290-293 MacTCP, 275-277
adding/removing, 291 UNIX and, 275
checking with xev, 292 X clients and, 271,275
disabling CAPSLOCK, 290 X serversand, 271,275
mapping, 290 macros, Xaccess file and, 59
mapping Backspaceto Delete, MacTCP, 276-277
290 magic cookie, 77-83, 98
switching Control and CAPS copying to a remote machine,
LOCK, 291 79
ksh command, 81 generating manually, 81-82
using with xdm, 78-79
using with xinit, 81-82
mail servers, archie, 250
bitftp, 237
last command, 214 ftpmail, 235-236
Idconfig command, 200 xstuff, 237-238
Idfcommand, 111 mailing lists, xpert, 233, 250
LD_LIBRARY_PATH environ- make program, 216-217, 256-258
ment variable, 30, 317 double colon syntax, 225
MIT X and, 317 -k flag, 225
OpenWindows and, 317 -n flag, 225
libraries, 4, 200, 216 tabs and, 222
building with ar, 199 targets; clean, 224;
errors, 320 depend,224;
for X, 303 Everything, 225;
(see also shared libraries.) includes, 224;
link trees, 196-197 install, 198,225;
little endian, 111, 170 install.man, 198,225;
Makefiles, 224;
World, 197, 224

Index 333
makeafbcommand,113 mre resourceeditor, 145-146
-Mflag, 126 .msfiles,242
Makefiles,214,216-217,222-223, mwm windowmanager,7, 19
254
comments in, 219
creating,256 N
make target, 215, 224
man command,213,242 nameserver, 168-169
.manfiles, 242 -name option,283-284
manpages,installing,207,213 nameddaemon,241
MANPATH environment vari- SIGHUPand, 241
able, 213 NCD X terminals, 162-163,
McGill University,248 170-171
Microsoft Windows, X servers remote configuration of,
and,271-275; 176-177
requirements,
272 netgroups,172
MIT, 4, 8 Network Computing Devices,
mit/, 191 (see NCD X terminals)
MIT-MAGIC-COOKIE-1, 77-83, Network File System, (see NFS)
98 Network Information System,
copying to a remotemachine, (see NIS)
79 networking, X terminals and, 162
using with xdm, 78-79 newkey command, 86-87
using with xinit, 81-82 newsgroups, 250
mkfile command, 180 comp.windows.x, 233, 250
mkfontdir command, 107, 114, NeXT computers, 189
116,139 X and, 271,277
fonts.scale, 107 NFS, exporting a filesystem, 239
monitors, 157-159 links and, 172
color support, 143, 158-159; netgroups, 172
measuring colors, 153 providing fonts with, 127, 163,
dot pitch, 158 172
grayscale support, 158-159 removing access,239
monochrome, 159 used with TFTP, 172
PC X servers and, 272 NIS, 86, 93
refresh rate, 159 adding a hostname,240
screen resolution, 158 ethers database, 165, 169, 242
screensize, 158 finding domain name, 85
static gray, 159 hosts database,240
virtual screens,158 SUN-DES-1and, 84
monochrome, 159 Secure RFC and, 84
mono-spaced fonts, 103 updating master from clients, 87
Motif, 7 ypmatchcommand,240
components of, 299-300 ypwhich command, 240
mre client, 145-146 nm command, 226
Motif Window Manager, (see nroff command, 242
mwm window manager) nslookup command, 241
mouse, 159-160 NVRAM, 164
optical, 159
trackball, 159
mouse buttons, redefining, 291
translation tables and, 288-290
moving windows, 19

334 X WindowSystemAdministrator's
Guide
 o advantagesand disadvantages,
271

olvwm window manager, 19 requirements,272

olwm window manager, 7, 19 restrictednumber of TCP/IP
Open Desktop, 8, 185 connections, 29
scologin, 68 server accesscontrol and, 83
xdm, 43 X terminals and, 162
OPEN LOOK GUI, 7 X386 (for UNIX derivatives),
OPEN LOOK window manager, 189
(see olwm window manager) PCF format, 111, 129, 170
openwin command, 37 converting BDF to, 112, 138
server access control and, 77 X terminals and, 171
OpenWindows, 8, 37, 185-187 .pcffiles, 111, 170
cm client, 118 X terminals and, 171
components of, 300-301 perl command, 81
fonts, 107; PEX, building, 199,213
aliases, 109; PHIGS, building, 199,213
Compat.list file, 126; pixel size, font name field, 102
converting, 125-126; pixels, 158, 161
example, 123-126; bits per, 159
Families.list file, 126; platform, determining type, 192
Synonyms.list file, 126 platform.cf, 204-206, 208-210,
installing, 190 210,223
props client, 145-146 point size, and font server, 129
setting searchpath for, 30 font name field, 102
xdm, 43 pointer keyword, 291
OPENWINHOME environment Point-to-Point Protocol, (see
variable, 30 PPP)
optimizing, 200 port (font server), 130
OSF/Motif, 7 Portable Compiled Font format,
componentsof, 299-300 (see PCF format)
(see also Motif.) porting programs, 226-230
OSMajorVersion build flag, 209 ports, used by font server,
OSMinorVersion build flag, 209 130-131, 133,136
OSName build flag, 209 used by X server, 96, 130
OSTeenyVersion build flag, 210 PostScript, color, 147
outline fonts, 110 Display, 186
documentation, 242
fonts, 111
printing, 242
release notes, 188
patch command, 195, 238, Type 3,111
260-263 PPP, 162
errors, 196 preprocessor symbols, searching
source code for, 195 for, 228
patch level, 194, 196 previewer, 115
patches, 186,259-264 principals, 85
applying, 194-196 for root, 85, 88-89;
getting with xstuff, 237 xterm client and, 92
PATH environment variable, 25, printing documentation, 242-243
29 private keys, 86
PC X servers, 162, 271-275 generating,90

Index 335
process
ID,of xdm,46 forNCDX terminals,
176-177
processes,
increasingnumberof, for TektronixX terminals,178
178-179 for Visual X terminals, 177
.profile file, 29, 36 of X terminals,161
ProjectRootbuild flag,207-208 remoteexecution,173
Projecttrnpl, 223 remotehosts,accessingfontson,
proportional fonts, 102 127
props resourceeditor, 145-146 remotelogins,34-36
.psfiles, 242 resizeclient, 31-33
.ps fonts, 111 -c flag, 33
pseudo-ttys,increasingnumberof, SHELLenvironmentvariable,33
179 -u flag, 33
pstat command. 180 resizing windows, 19, 31-33
ptys, increasing number of, 179 resolution, 158
public domain software, 247-268 resolver, 170
compiling, 255-268 resource editors, 145
finding sources,247-250 resources, 6, 8, 24, 281-290
patching, 259-264 and client -name option,
untarring, 252 283-284
public keys, 85-86 and client -xrm option, 286
generating,87; app-defaults files, 258
for root, 87 application defaults, 103, 285
propagating to NIS master,87 background, 144
chooser, 57, 60
class names, 283-285;
learning, 284
color and, 145
Quarterdeck Office Systems, configuration files; .Xdefaults,
271-272 286-287;
queries, XDMCP,55-59, 164, 173 .Xdefaults-hostname,285;
.Xresources, 15,24-25,286
defining, 281-286
R font specification, 103
foreground, 144-145
random numbers, 81 instancenames, 283-284;
ranlib command,199 learning,284
RARP,165 loadinginto servers,24-25,
X terminals and, 164 287-288
rarpd daemon,165 loosebindings,52, 282
rdist program, 200,203 overriding,283
exampledistfile,203 readgloballywith xdm,286
exampleusage,203 sample,15
sharedlibraries,203 server-specific,
66
specialcommand,203 syntax,281-284
releasenotes,188-189,192-193, tightbindings,52, 282
205 tracing,286
RELNOTES.TXT, 188-189, translation tables, 288-290
192-193,205 usingfont aliasesin, 109
remote clients, setting DISPLAY XAPPLRESDIRenvironment
for, 36 variable,258
starting,34-36 xconsole,60, 62
remoteconfiguration,175-178 xdm,46, 51,51-60;
advantagesof, 175

336 X WindowSystemAdministrator's
Guide
resources, xdm (cont'd) screen size, 158
DisplayManager*authName, screendump command, 96
84,88; screenload command, 96
DisplayManager* authorize, screens, 6, 27
78, 84, 88; search path, setting,29-30;
DisplayManager*reset,95; in startup script, 25;
DisplayManager* startup, 95 mixed environments, 30;
XENVIRONMENTenvironment OpenWindows, 30
variable, 258 secure keyboard option, xterm,
xlogin, 60-62 93
xrdb, 24 Secure RFC, 76, 85-86
Reverse Address Resolution Pro- chkey command, 86
tocol, (see RARP) generatingpublic key, 87;
reverse video, 23 for root, 87
rexec command, 173 newkey command, 86
rgb command, 146 obtaining, 86
RGB system, 143 overview, 85-86
aliases, 145 principals, 85;
alternate databases, 147 for root, 85
color names, 144-145 propagating public key, 87
defining colors, 146-147 SUN-DES-1and, 84-93
fixing corrupted database,147 security, 73-98
hexadecimal color values, 145; console windows, 94-96
converting to decimal, 146; /dev/kmem, 202
Xcms and, 148 /etc/fbtab, 97
triplets, 143 framebuffer, 97
Xcms and, 147 host-based access control,
rgb.dir file, 146 74-77;
rgb.pag file, 146 /etc/Xn.hosts, 74-75;
rgb.txtfile, 144-146 PC X serversand, 83;
.rhosts file, 35, 81 problems with, 76-77;
Secure RFC and, 86, 90 X terminals and, 75-76, 79,
rlogin command. 34 83;
root menu, 14-15, 19,26 xhost client, 75-77
root window, 14 kmem group, 202
rooted and rootless X servers, server access control, 73-93;
275 X terminals, 175
rpc.ypupdated daemon, 87 TFTP, 167-168
rsh command, 35-36, 79, 81 user-based access control,
xrsh command and, 79 77-93;
.rules files, 222 MIT-MAGIC-COOKIE-1,
-rv option, 23 77-83;
SUN-DES-1, 84-93;
XDM-AUTHORIZATION-1,
83-84, 207
xload permissions,202
scalable fonts, 105,110-111 xterm permissions,202
SCO UNIX, increasing number of (see also accesscontrol.)
processes,179 Serial Line Internet Protocol,
increasing number of ptys, 180 (see SLIP)
scologin, 43, 68 serial X sessions, 160, 162
screen dumps, 96
screen resolution, 158

Index 337
SerialXpress,162 servers,
131
ServerNatural Format, (seeSNF SIGUSR1 signal,rereadingconfi-
format) gurationfile ,131
servers,157 SIGUSR2 signal,flushingfont
for Archie,248 cache,131
(seealsofontserver;mail Silicon Graphics,(seeSGI)
servers;X servers.) Silicon Graphicscomponents,
setenv command, CHOWNPROG 302-303
and,211 site.def,204-205,223
DISPLAYand, 27-28, 164 slant, font name field, 101
FONTSERVERand, 134 SLIP, 162
LD_LIBRARY_PATH
and,30, SNFformat, 107, 111,125,129
317 converting BDF to, 112, 114
MANPATHand, 213 converting to BDF, 112
TERM and, 204 differences, 170
TMPDIRand, 199 .snffiles, 107, 111, 170
XCMSDBand, 149, 151 differences, 170
XENVIRONMENTand, 258 snftobdf command, 112
setupmenu,X terminals,164 software,publicdomain,247-268;
SGI, 132-133, 185 compiling, 255-268;
sgi.cf, 208 finding sources,247-250;
SHAPEextension, 190 patching, 259-264;
shar files, 262 untarring, 252
shared libraries, 319 Solaris, 189
building, 223 Solbourne window manager, (see
installing, 200, 203; swm window manager)
with rdist, 203 source code, patch command, 195
Idconfig command, 200 servers, 193
LD_LIBRARY_PATH and, 30 Xll, 185-186, 188-189;
shell environment, 27-36 disk spacefor, 191;
defining searchpath, 29-30 link trees, 196
SHELL environment variable, 33 sources, 247-268
showrgb command, 23, 144 compiling, 255-268
SIGHUPsignal, inetd, 88, 168 finding, 247-250
named, 241 patching, 259-264
resetting font servers, 131 spacing, font name field, 102
Xaccessfile, 59 .spd files, 111
xdm, 45, 52, 55, 59, 67-68, 78 Speedo fonts, 105, 110-111, 129
Xservers file, 55 fonts.scale and, 107
SIGTERM signal, xdm, 68 startup script, 25-26
signals controlling process,26
SIGHUP; foreground process,26
font server, 131; setting searchpath, 25
inetd, 168; .xinitrc, 25-26, 38-39
named, 241; .xinitrc vs. .xsession, 39
xdm, 45, 52, 78 .xsession, 14, 18, 25-26, 29, 33,
SIGTERM;font server, 131; 37,39
xdm, 68 startx command, 37-38
SIGUSR1;
font server,131 staticgray, 159
SIGUSR2;
font server,131 sticky bit, 97
SIGTERMsignal,killing font stringscommand,192,229
StripInstalledPrograms build
flag,207

338 X WindowSystem Administrator'sGuide

style, font namefield, 102
subnet mask, 168
Sun OpenWindows, components tabs, and make, 222
of, 300-301 tail command, 197
Sun workstations, as X terminals, -fflag,197
243 TakeConsole, 47, 95
fonts and, 170 tar command, 238, 252
framebuffers, 96-97; .tar files, 238
dual screens,244 targets, (see make program, tar-
multiple screens,244 gets)
sun.cf, 208, 210 tbl command, 242
SUN-DES-1, 76, 83-93 .tbl files, 242
adding another user,91-92 TCP/IP, 162
error messages,92-93 connecting via, 28
prerequisites,86-88 font server and, 136
running clients from a remote port used by font server, 130
domain, 91-92 port used by X server, 96
using with xdm, 88 restricted number of connec-
using with xinit, 89-90 tions, 29
xterm client and, 92 Tektronix, 147
SunOS, 187-188, 196 X terminals, 162, 171;
dual framebuffers, 244 remote configuration of, 178
increasing number of ptys, 179 telnet command, 164, 248
increasing number of users, 179 X server,96
increasing processes, 178 temporary files, redefining direc-
increasing swap space, 180-181 tories for, 199
installing font server on, 131 TERM environment variable, 31
installing xdm on, 69 termcap, 31-32, 204
rebuilding kernel, 179 entriesmissing from, 318
reconfiguring for X terminals, terminal databases, 31
178-181 terminal emulation, xterm, 31
trace command, 286 terminal type, setting, 31
swap files, 180 terminals, (see X terminals)
swap space, increasing, 180-181 terminfo, 31-32, 204
swappingto disks, 180 entries missing from, 318
swappingto files, 180 TeX, 115
swapon command, 180-181 TFTP, booting with, 127, 163, 165,
swm window manager, 19 167-168
symbols, preprocessor,searching links and, 172
for, 228 providing fonts with, 127, 163,
undefined, 226 171-172
Synonyms.list file, 109, 126 restrictedmode, 167, 171
syslog daemon, 129-130, 169 securemode, 167, 171
syslog.conf file, 169 testing, 167
System V, boot files, 132-133 used with NFS, 172
installing font server on, /tftpboot, 163, 167, 170-171
132-133 tftpd daemon, 167
system.twmrc file, 18-19 errors, 169
tic command, 204
tight bindings, 52, 282
titlebar, 19
tmp directory, changing, 199
.tmpl files, 222

Index 339
/tmp/.Xll-unix/XO
file,97 userID, finding,85
toolkits, 7 user-basedaccesscontrol, 77-93
trace command, 286 overridden by host-based
trackballs, 159 accesscontrol,82-83,175
translation tables, 288-290 MIT-MAGIC-COOKIE-l,77-83,
triplet, RGB,143 98;
Trivial File Transfer Protocol, using with xdm, 78-79;
(seeTFTP) using with xinit, 81-82
troff, (see nroff command) SUN-DES-1,84-93;
truss command, 286 adding another user,91-92;
trusted-clients (font server), 130, error messages,92-93;
136 running clients from another
tset command, 31 domain, 91-92;
tvtwm window manager, 19 using with xdm, 88;
twm window manager, 18-19 using with xinit, 89-90;
configuring, 19 xterm client and, 92
iconifying windows, 19 XDM-AUTHORIZATION-1,
moving windows, 19 83-84;
resizing windows, 19 using with xdm, 84
root menu, 14-15, 19,26 X terminals and, 175
sampleconfiguration, 15 use-syslog (font server), 129-130
titlebar, 19 uudecode command, 195,236,
.twmrc file, 19 238
sample, 15 uuencode command, 195,238
uwm window manager, 191

Ultrix, 187-188,226
installing xdm on, 70 vendor-distributed X, and xdm,
uname command, 192 43
uncompress command, 238, 242 vendor-specific fonts, 117-126
uncompressing files, 252 vertical resolution, font name
undefined symbol errors, 226 field, 102
unshar command, 262 virtual root window, 19
untarring files, 252 virtual screens, 158
Usenet, 233 Visual X terminals, 171, 174
user environment, 9 font server and, 171
configurationfiles, 14 remoteconfigurationof, 177
configuring, 13-39
defining searchpath, 29-30
environment variables, 29 VV
login shell and, 33-34
resources,24 wait command, 26
sampleX session,13-15 weenies, TeX font, 115
shellenvironment,
27-36 weight, font namefield, 101
startupmethods,37-39 widgets,7, 283
startup script, 25-26; resourcesand, 281
controllingprocess,26; wildcards, * (asterisk),56-57
foregroundprocess,26; andspecifyingfonts,108
settingsearchpath,25 windowmanagers,7,15, 17-19
templates, 18
unconfigured, 16-17

340 X WindowSystemAdministrator's
Guide
window managers (cont'd) XI1R5 components,298-299
as local clients on X terminals, X administration, color, 143-153
161 font administration, 101-140
gwm, 19 introduction to, 8-10
mwm, 19 multiple machines, 10
olvwm, 19 philosophy of, 10
olwm, 19 security, 73-98
swm, 19 user environment, 18
tvtwm, 19 X terminals, 157-181
twm, 18-19 X clients, (see clients)
uwm, 191 X Color Management System,
windows, iconifying, 19 (seeXcms)
moving, 19 X command, 16, 38,53
resizing, 19, 31-33 -auth option, 81-82
specifying location of, 20-22 -fp option, 117
specifying size of, 20-22 setting default font path, 106
titlebar, 19 X Consortium, 4, 8
workstations X Display Manager, (see xdm)
diskless, 162; X Protocol, 3, 98
fonts for, 127 X resources, (see resources)
World, make target, 197, 224 X servers, 3-6, 167
wtmp file, 214 accesscontrol, 73-93;
host-based (see host-based
access control);
reasons for, 73;
user-based (see user-based
X, AlXWindows components,302 accesscontrol);
building; (see building X) X terminals, 175
client-only distribution, 189 adding fonts, 114-126
configuring, 204-214 backing store, 161
DECWindows components, color support, 143-153,
301-302 158-159

design, 3-7 controlled by xdm, 53-55

development distribution, 187 depth, 159
distribution directories, 297 dimensions, 158
execution-only distribution, 187 display classes,65-66
graphics files, 302-303 DOS-based,272-275;
installing; (see installing X) requirements,272
libraries, 303 dot pitch, 158
multiple distributions, 189 font path, 105-106;
on multiple machines, 10 default, 106,212
OSF/Motif components, fonts, 101-140;
299-300 byte order, 170-171;
portability of, 4 caching, 115;
running multiple releasesof, 30 linking, 170
source code, 185-186, 188-189 grayscale support, 158-159
Sun OpenWindows compo- hanging remotely, 96
nents, 300-301 in xdm resource names, 52
user environment, 9, 13-39 installing for X terminals, 163
vendor-supplied distributions, keyboards, 159-160
186-187 Macintosh computers and, 271,
275
Microsoft Windows and, 271

Index 341
X servers(cont'd) font serversupport,160,163,
monitors,157-159 171
mouse,159-160 fonts,127,170-172;
MS-Windows-based,272-275; byte order, 170-171;
requirements,
272 diskspace
and,170-171;
NeXTcomputersand,271,277 downloading,163,171-172;
refreshrate, 159 font tape, 170;
rooted and rootless,275 installing, 163;
screenresolution, 158 linking, 170
screensize, 158 grayscale support, 158-159
screens,6, 27 hardware addresses,165, 169
server-specific
resources,
66 in Xserversfile, 53
SHAPEextension, 190 installing the server, 163
starting, 38 IP addresses,164;
starting with user-basedaccess getting with BOOTP,
control, 81-82 165-166;
supportedby MIT, 193 getting with RARP, 165;
using from different releases, nameserver and, 169
190 keyboards, 159-160
virtual screens, 158 local clients, 161
X command,53 memory, 158, 161
X terminals, 157-181 monitors, 157-159
X386, 189 mouse, 159-160
XDMCPqueries,45, 53, 55-59 network interface, 162
XNeXT, 189 network setup, 164-170
.xserverrc and, 38 network traffic, 158
Xsun,244 NVRAM, 164, 168
(seealso X terminals.) peripheral support, 161
X session, configuration files, 14 refreshrate, 159
configuring, 13-39 remoteconfiguration, 161,
defining searchpath,29-30 175-178;
login shell and, 33-34 advantagesof, 175;
sample, 13-15 for NCD X terminals,
shell environment, 27-36 176-177;
starting with xdm, 63-65 for Tektronix X terminals,
startupmethods, 37-39 178;
startup script, 25-26; for Visual X terminals, 177
controlling process,26; screenresolution, 158
foreground process,26; screensize, 158
setting searchpath, 25 serial connections, 160-162
unconfigured, 16-17 server accesscontrol, 74-76, 79,
xinit vs. xdm, 37-38 83,175;
X terminals, 3, 9, 157-181 host-based,175;
backing store, 161-162 user-based,175
booting, 167-168 server software, 160;
color support, 158-159 FLASHROM, 160;
configuring for xdm, 173-175 ROM, 160;
configuringfor XDMCP, runningon host,160
173-175 settingup, 163-164;
depth,159,161 stepsfor, 163
displayclassesand,55 setupmenu,164
dot pitch, 158 telnet window, 164
virtual screens, 158

342 X WindowSystemAdministrator's
Guide
X terminals (cont'd) xclock client, 14, 16
xdm and, 53 Xcms, 144, 147-153
XDMCPsupport, 53, 160 aliases, 149
xmodmap and, 291 CIE, 147
X Toolkit Intrinsics (Xt), 7 client database, 148
X Window System, (seeX) color database;example, 151
Xll, (see X) color names, 148-151
Xll/NeWS, 110 color spaces, 147-148, 150;
fonts, 111, 125; listing of, 148
converting to BDF, 125; defining colors, 150-151
converting to SNF, 125 device profiles, 152-153
X11R3, xdm, 45, 65 RGB system and, 147
Xservers file, 53, 55 specifying colors, 148
X11R5, components of, 298-299 XCMSDBenvironment variable,
X386, 189 149
Xaccess file, 47, 55-59, 164, 174 Xcms.txt file, 148-150;
* (asterisk), 56-57 example, 149
! (exclamation point), 56 xcmsdb client, 152-153
% (percent sign), 59 .xinitrc example, 153
BROADCASTkeyword, 57 XCMSDB environment variable,
chooser client and, 57-59 149, 151
CHOOSERkeyword, 57 Xcms.txt file, 148-150
defining macros, 59 example, 149
excluding, 56 xcoloredit client, 145-146
including, 56 xcolors client, 144
rereading, 59 XCOMM (imake comment), 220
SIGHUPsignal, 59 xconsole client, 26
syntax, 56-59 resources,60, 62
XAPPLRESDIR environment xdm and, 62
variable, 258, 286 .Xdefaults file, 286-287
xarchie client, 248, 251-259 .Xdefaults-hostname file, 285
xauth command, 36,79-83,93 xdm, 9, 25, 37, 43-70
adding a code. 81 aborting, 61
commands; add, 81; changing greeting, 61
extract, 79; chooser and, 53,57-59
list, 84, 88; command-line options;
merge,79 -config, 46, 52, 67;
copying magic cookie to remote -debug, 65
machine, 79 concepts, 44-45
overridden by xhost client, configuration files, 46-66;
82-83 installing, 206;
SUN-DES-1and, 89 overriding, 67;
using with xinit, 81-82 rereading,52, 55, 59, 67-68;
xrsh command and, 79 Xaccess, 55-59, 164, 174;
.Xauthority file, 77-83 xdm-config, 51-52, 78, 84,
adding a code, 81 95;
extracting code from, 79 Xresources, 60-62;
merging new entry, 79 Xservers, 53-55, 65, 174;
SUN-DES-1 and, 85, 89-90 Xsession, 63-65, 286
using with xinit, 81-82 configuring, 51-66
47 configuring login box, 60-62
xcalc client, 14
translation tables and, 288-290

Index 343
xdm (cont'd) MIT-MAGIC-COOKIE-1,
configuringX terminalsfor, 78-79;
173-175 SUN-DES-1,88;
customizing,51-66 XDM-AUTHORIZATION-1,
default environment, 49 83-84
displayclasses,
52,55, 65-66 server-specificscripts,64
easysetup,48-49 starting,48, 67
errormessages,
46, 63 startingautomatically,69-70
Fl and, 61,63 starting X session,63-65
failsafe session,50, 61, 63 testing, 66-68
font serverand, 131, 133 troubleshooting,49-51
history,45 vendorenvironments
and,43
host accesscontrol, 47, 55-59 vs. xinit, 37-38
installing,69-70 X terminalsand,53, 160,
installing DBS code, 207 173-175
installing; on AIX, 70; X11R3,45,53,65, 174
on IRIX, 70; xconsole client and, 62
on SunOS,69; xmodmap and, 291
on Ultrix, 70 XDM Control Protocol, (see
managinganother workstation, XDMCP)
53 XDM-AUTHORIZATION-1, 83,
Open Desktop, 43 83-84, 207
OpenWindows,43 using with xdm, 84
problemslogging in, 49-51 xdm-config file, 46, 51-60, 78, 84,
processID, 46 95
rereadingconfiguration files, overriding, 67
52,55,59,67-68 syntax, 51-52
resources, 51-60; XDMCP, 45, 174
display classes,52; broadcastqueries, 55-57, 173;
Display Manager.J3. setup, and subnet, 173
62; configuring X terminals for,
Display Manager*authName, 173-175
84, 88; direct queries, 55-57, 173
Display Manager*authorize, display classes,65
52,78,84,88; host accesscontrol, 47
DisplayManager.autoRescan, indirect queries, 55, 57-59, 173
52,55,59,67; queries, 55-59, 164, 173;
DisplayManager.errorFile, workstations and, 53
63; server accesscontrol and, 77;
DisplayManager.pidFile,68; MIT-MAGIC-COOKIE-1,
DisplayManager*reset, 95; 78-79;
DisplayManager*session, SUN-DES-1,88;
63-64; XDM-AUTHORIZATION-1,
DisplayManager*startup, 95; 83-84
server-specific,52 X terminals and, 160, 173-175
restarting with xdm-pid, 68 Xservers file and, 53
CTRL-Rand,61 xdm-errors file, 46,49-50, 63
CTRL-RETURNand,61,63 xdm-pid file, 46, 68
SIGHUP
and,45, 52, 78 xdpyinfo client, 158
SIGTERMand, 68 xdvi client, 115
SCO version; (see scologin) XENVIRONMENT environment
server accesscontrol and, 81; variable, 258, 285
xev client, 291-293

344 X WindowSystemAdministrator's
Guide
xfd client, 103, 108, 115 #ifdef commands, 287
XFILESEARCHPATH environ- #include commands, 287
ment variable, 286 -load option, 288
xfontsel client, 20, 104 -merge option, 288
xhost client, 28, 35-36, 74-77, 93 pre-defined symbols, 287
overriding xauth command, -query option, 288
82-83 Xremote, 162
SUN-DES-1 and, 85, 88-90 Xresources file, 62-65
xrsh command and, 79 .Xresources file, 24-25, 47, 64,
xinit command, 16, 25, 37-38 286
- flag, 38, 82, 89 sample, 15
configuration files; installing, -xrm option, 286
206; xrolodex client, 247
.xinitrc, 37-38, 90; xrsh command, 36, 79
.xserverrc, 38; XRSH_AUTH_TYPE and, 79
.xserverrc, 82 XRSH_AUTH_TYPEenvironment
-dev flag, 38 variable, 79
server access control and, xsccd client, 153
81-82,89-90 .xserverrc file, 38
setting default font path, 106 server accesscontrol and, 82
using xauth with, 81-82 Xservers file, 46, 48, 53-55, 65,
vs. xdm, 37-38, 43 174
.xinitrc file, 16, 25-26, 37-39 default font path, 106
SUN-DES-1and, 90 display classes,55
xcmsdb and, 153 rereading, 55
xkeycaps client, 264-268, 291 SIGHUPsignal, 55
Xlib, 7 syntax, 53
xloadimage client, 96 XI1R3, 53,55
xlogin widget, resources,60-63 XDMCPand, 45, 53
xlsfonts client, 20, 103, 108 Xsession file, 18, 45-46, 63-65
xmessage client, 33 .xsessionand, 64
xmkmf command, 214-215, 256 .xsession file, 25-26, 39, 45, 47,
-a flag, 215, 266 49,63
xmodmap client, 264, 290-293 bypassing, 50, 64
checking keysyms with xev, C shell, 29
292 controlling process,50
disabling CAPSLOCK, 290 default searchpath, 29
mapping Backspaceto Delete, error messages,39
290 failsafe session, 50
-pk option, 291 foreground process,50
redefining pointer, 291 problems with, 49-51
switching Control and CAPS sample, 14
LOCK, 291 Xsession and, 64
X terminals and, 291 .xsession-errors file, 47, 49-50,
.Xmodmap file, 291 63-64
XNeXT, 189,277 problems with, 50
xpert mailing list, 233, 250 xset client, 105, 116, 124
xpostit client, 14, 249 font serverand, 136-137
xrdb client, 24-25, 60-61, 64, 285, fp option, 105, 114, 136
287-288 fp rehashoption, 106, 115, 124
cpp and, 287 -q option, 105, 137
-D option, 287 xset command, fp option, 172
#define commands, 287 xsetroot client, 25

Index 345
Xsetup_0 file, 47
Xstartup file, 47
xstuff, 237-238
Xsun, 38, 244
xterm client, 14,16
-bg option, 144
build flags, 214
-C option, 94
console windows, 94
-fg option, 144
-fn option, 20, 103
fonts, 101, 106
-geometry option, 20
installing terminal definition for,
203-204

login shell, 33-34

-Is option, 33-34
resized windows, 31-33
resources; font, 15;
loginShell, 33;
savedlines, 15;
scrollBar, 15
SUN-DES-1security and, 92
scroll bar, 15
securekeyboard feature, 93-94
shell issues, 31-34
terminal emulation, 31
VT100 widget, 24
xtex client, 115-117
xtici color editor, 150-151
xtrek client, 138
XUSERFILESEARCHPATH envi-
ronment variable, 286
XView toolkit, 7
xwebster client, 259-264

Yellow Pages,(see NIS)

ypbind command, 87
ypmatch command, 85-86, 240
ypwhich command, 86, 240
.Z files, 107, 112, 236, 238, 242

zcat command, 238, 242, 252

zmail client, 33

346 X WindowSystemAdministrator's
Guide
 About the Authors

Linda Mui started working for O'Reilly & Associates in 1986.She was first hired as a production
assistant,later becamean apprenticesystem administrator, and is now a writer. Her first writing job
was for termcap and terminfo, which she co-authoredwith John Strang and Tim O'Reilly. Shealso
wrote Pick BASIC, on programming applications for Pick systems.In between writing jobs, Linda
works on troff macros and tools for the O'Reilly & Associates production staff.

Linda was raised in the Bronx, New York and now lives in Cambridge, Massachusetts.Lately she
has beentrying to improve herself by learning how to swim, play billiards, and accessorize.

Eric Pearce is an author and technical resource for O'Reilly & Associates. In addition to co-
authoring this book, he is also responsible for developing CD-ROM companion disks for books
produced by O'Reilly & Associates. Eric's interests include promoting public domain software,
Internet connectivity and network services.

Before coming to work for O'Reilly & Associates, Eric worked as a systems programmer for Boston
University, which he also attended as a student. His favorite activities include bicycling, snow-
boarding, rock climbing, and dangeroussports.
Volume 0: X Protocol Reference Manual Volume 2: Xlib Reference Manual
for X11 Release 4 and Release 5 for X11 Release 4 and Release 5
Editedby AdrianNye By AdrianNye
3rd Edition,February1992 3rd Edition,June 1992
Volume
0,XProtocolReference
Manual,describes
the Volume
2, XlibReference
Manual,is a complete
pro-
X NetworkProtocolwhich underliesall softwarefor grammer'sreferencefor Xlib, updatedfor XI1 Release
Version
11oftheXWindow
System.
Themanual
is 4 andRelease
5.
updated
for R5.Contents
aredividedintothreeparts: Includes:
PartOneprovides
a conceptual
introduction
to theX " Reference
pages
forXlibfunctions
Protocol. It describestherole of theserverand client " Referencepagesfor eventtypes
and demonstrates the network transactions that take " Permuted links to Xlib functions
placeduringa minimal client session. " Descriptionof macrosand referencepagesfor their
function versions
PartTwocontains
anextensive
setof reference
pages
foreach
protocol
request
andevent.
It isareformatted " Listing
oftheserver-side
colordatabase
andreorganized
version
oftheConsortium's
Protocol " Alphabetical
indexanddescription
ofstructures
specification.
Allmaterial
fromtheoriginal
document " Alphabetical
indexanddescription
ofdefined
symbols
is present
in thismanual,andthematerial in therefer- " KeySyms andtheirmeaning
encepages is reorganized
to provideeasieraccess. " Illustration
of thestandard cursorfont
Eachprotocolrequestor eventis treatedasa separate, " Function groupindexto therightroutinefor apartic-
alphabetizedreference
page.Reference pages include ulartask
theencoding requests
andreplies. " Reference pages for Xlib-related
Xmufunctions(mis-
cellaneousutilities)
PartThreeconsistsof severalappendixesdescribing
particular
parts
oftheXProtocol,
along
withseveral " attributes
4single-page
reference
aidsfortheGCandwindow
reference aids. It includes the most recent version of
theICCCM
and
theLogical
FontConventions
Manual. New
features
inthe3rdEdition
include:
" Over100new manpages coveringXcms,internation-
TheThirdEditionof Volume
0 canbeusedwithany alization,and thefunctionversionsof macros
release of X.
" Updatingto the R5spec
516pages,ISBN:1-56592-008-2 " New "Returns" sections on all the functions which
returnvalues,makingthis informationeasierto find
Volume1: Xlib ProgrammingManual 1138pages,ISBN:1-56592-006-6
for X11 Release 4 and Release 5
ByAdrian Nye
3rd EditionJuly 1992
Newlyupdatedto coverXI1 Release 5, Volume1, Xlib
ProgrammingManual is a completeguideto program-
mingto theX library (Xlib), the lowestlevelof pro-
gramminginterfaceto X. Newfeaturesincludeintro-
ductionsto internationalization,device-independent
color,fontservice,
andscalable fonts.
Includeschapterson:
" X WindowSystemconcepts
" Simpleclient application
" Window attributes

" Thegraphicscontext Xlib

" Graphics
in practice Programming
Manual
" Color and Events
" Interclient communication

" TheResourceManager
" A completeclient application
" Windowmanagement
824pages,ISBN:1-56592-002-3
ORDERTOLL-FREE
IN US/CANADA, YAM- SPMPST, 1-800-998-9938
 Volume
3: X Window
SystemUser'sGuide Volume
3M: X WindowSystemUser's
for X11 Release 4 Guide OSF/Motif Edition
By ValerieQuerciaand Tim 0 'Reilly ByValerieQuercia andTimO'Reilly
3rdEdition,May1990 2ndEdition,January1993
Volume 3, X Window System User's
Guide,orientsthe Newlyrevisedfor Motif1.2andXI1 Release 5, this
newuserto windowsystem conceptsandprovides alternative
editionof theUser'sGuidehighlights
the
detailed
tutorials
for manyclientprograms,
including Motifwindowmanager andgraphical
interface.It will
thextermterminalemulator andwindowmanagers. bethefirstchoicefor themanyuserswiththeMotif
Building
onthisbasic
knowledge,
laterchapters
explain graphical
userinterface.
howto customize
theXenvironment
andprovidesam- Topics
include:
ple configurations. " Overviewof the X ColorManagement
System(Xcms)
Thispopular
manual
isavailable
intwoeditions,
one " Using
theX fontserver
for usersof theMITsoftware,onefor usersof Motif. " Bitmapand xmag
TheStandardEditionusesthetwm managerin most " Tear-offmenusand drag-and-drop
examples andillustrations,
andhasbeenupdated for " Startingthesystem andopening clientwindows
XI1 Release4. " Usingthextermterminalemulator
Topicsinclude: " Usingstandard release
clients
" Starting
thesystem andopening windows " UsingMotifsmwmwindowmanager
" Usingthextermterminal emulator andwindow " Customizing thekeyboard, displayandbasicfeatures
managers of anyclientprogram
" Moststandard releaseclients,including
programsfor " Performing system administration
tasks,
suchasman-
graphics,
printing,fontmanipulation,window/display agingfonts,startingXautomatically,
andusingthedis-
information,
removing windows, aswellasseveral playmanager to runXonsingleor multipledisplays
desktop
utilities Motif
Edition:
956pages,
ISBN:
1-56592-015-5
" Customizingthewindowmanager,keyboard,display,
andcertainbasicfeatures
of anyclient program
" Usingandcustomizing themwmwindowmanager,
for thoseusingtheOSF/Motifgraphical
userinterface
" System administration
tasks,
including
managing
fonts,starting
Xautomatically,
andusingthedisplay
manager, xdm,to runXonasingleor multiple
display
StandardEdition: 752pages,
ISBN:0-937175-14-5

VolumeThree VolumeThree

X Window System X Window System

User'sGuide User's Guide

SENDE-MAILQUESTIONS
[email protected]
ORUUNET!ORA!HUTS
Volume* X ToolkitIntrinsics Volume 5: X Toolkit Intrinsics Reference
Programming Manual for X11 Release 4 Manual for X11 Release 4 and Release 5
ByAdrian Nyeand Tim 0 'Reilly Editedby DavidFlanagan
Standard:2nd Edition,September1990 3rd Edition,April 1992
Motif:
2nd Edition,
August
1992 Volume
5,XToolkit
Intrinsics
Reference
Manual,
isa
Volume4 is acompleteguideto programmingwiththe completeprogrammer's
referencefor theX Toolkit.It
XToolkitIntrinsics,
thelibraryof Clanguage
routines provides
reference
pages
for eachof theXtfunctionsas
thatfacilitate
thedesign
ofuserinterfaces,
withreusable wellasthewidget
classes
defined
byXtandtheAthena
components
calledwidgets.It provides
concepts
and widgets.
examples
thatshow
howtousethevarious
XToolkit Thisvolume
isbased
onXtdocumentation
fromMIT
routines.
Thefirstfewchapters
aredevoted
tousing and
has
been
re-edited,
reorganized,
andexpanded.
widgets;
theremainder
ofthebookcovers
themore Contents
include:
complex
task
ofwriting
newwidgets. " Reference
pages
foreach
oftheXtIntrinsics
and
Volume 4is available
in twoeditions.TheStandard macros,
organized
alphabetically
for easeof use
EditionusesAthenawidgetsin examplesfor XI1 " Reference
pages
for theinterface
definitionsof func-
Release4 to demonstrate
how to useexistingwidgets tions registeredwith other Xt functions
butprovides
a goodintroduction
to programmingwith " Reference
pages
for theCore,Composite,
and
anywidgetsetbasedonXt. TheMotifEditionusesthe Constraint
widgetmethods
Motif 1.2widgetsetin examples,and hasbeenupdated " Referencepagesfor the Object,RectObj,Core,
for XI1 Release5. Both booksinclude: Composite,Constraint,andShellwidgetclasses
" Introduction
totheXWindowSystem defined
byXt
" Building
applications
withwidgets " Reference
pages
forAthena
widget
classes
" Constructing
abitmap
editor
withwidgets " Reference
pages
forXt-related
Xmu functions
" Basicwidget
methods " Permuted
index
" Events,
translations,
andaccelerators " Many
appendixes
andquickreference
aids
" Event
handlers,
timeouts,
andworkprocedures " Index
" Resource
management
andtypeconversion The3rdEditionof Volume
5 hasbeencompletely
" Selections
andwindow
manager
interaction revised.
In addition
tocovering
Release
4 andRelease
" Geometry
management 5ofX,allthemanpageshavebeencompletely
rewrit-
" Menus,gadgets,andcascadedpop-ups ten for clarityandeaseof use,and new examplesand
" Miscellaneous
techniques descriptions
have
been
added
throughout
thebook.
" Comparison
ofAthena,
OSF/Motif,
andAT&T
OPEN 916pages,
ISBN:
1-56592-007-4
LOOKwidgets
" Master index to volumes 4 and 5

Thisbook is designedto be usedwith Volume5, X

Toolkit Intrinsics ReferenceManual, whichprovides
referencepagesfor eachof the Xt functionsand the
widgetclassesdefinedbyXt.Volume5.
StandardEdition:624pages,ISBN:0-937175-56-0
MotifEdition: 714pages,ISBN1-56592-013-9 loThe
Definitive
the Guides
XWindow
Systen

X Toolkit Intrinsics X Toolkit Intrinsics

Programming Manual ReferenceManual

ORDERTOLL-FREE
IN US/CANADA, /AM - SPMPST, 1-800-998-9938
 Volume
6: MotifProgramming
Manualfor Xasawhole.
Itcomplements
andbuilds
upon
theear-
OSF/Motif Version 1.1 lier booksin theXWindow
System
Series
fromO'Reilly
& Associates,
as well ason OSF'sown Motif StyleGuide.
By Dan Heller
1stEdition,
September
1991 Does
notcover
UIL.
The
Motif
Programming
Manual'^
asource
forcom- 1032
pages,
ISBN:
0-937175-70-6
plete,accurate,
andinsightful
guidance
onMotifappli-
cation
programming.
There
isnootherbook that
cov- Volume7: XViewProgramming
Manual
erstheground
asthoroughly
oraswellasthisone. anilXViewReference
Manual
TheMotif'Programming
Manual
describes
howto Edited
byDanHeller
write
applications
using
theMotif
toolkit
fromtheOpen Programming
Manual:
3rdEdition,
September
1991
Software
Foundation
(OSF).The
book
goes
intodetail Reference
Manual:
1st
Edition,
September
1991
onevery Motifwidget
class,
withusefulexamplesthat Volume 7,XViewProgrammingManual, hasbeen
willhelpprogrammers todeveloptheirowncode. revised
andexpandedforXView
Version 3. XView
was
Anyone doingMotifprogramming whodoesn't wantto developedbySunMicrosystems
andis derived
from
have tofigure
it outontheirownneeds thisbook. Sun's
proprietary
programmingtoolkit,SunView.
It is
Inaddition
toinformation
onMotif,
thebook
isfullof aneasy-to-use
object-oriented
toolkit
thatprovides
an
tips aboutprogrammingin general,and aboutuser OPENLOOKuserinterfacefor X applications.
interface
design. ForXViewVersion
3,themajoradditions
are:
Contents
include: " Internationalization
support
forXViewprograms
" Anintroduction
totheMotif
programmingmodel, " AnewDrag andDrop
packagethatletstheusertrans-
howit isbased
ontheXToolkit
Intrinsics,
andhowit ferdatabetween
applications
bydragging aninterfac
differsfromthem objectto aregion
" Chapters
oneach
oftheMotif
widgetclasses,
explain- " Amouseless
input
modelthatmeans
XView
applica-
ingthemindepth,
withuseful
examples
thatwillhelp tions
canbecontrolled
fromthekeyboard
without
a
youtoimprove
yourowncode.Forexample,
the mouse.Soft
function
keysarealso
supported
chapteronmenus shows howto develop
utilityfunc- " TheNotices packagehasbeencompletelyrewritten
to
tionsthatgeneralize
andsimplifymenucreation.All incorporateNoticeobjects
of thecodeshownin thebookis available
freeof " TheSelectionpackagehasbeenrewritten,replacing
charge overtheInternetorviaUUCP theSunView-style
selection
service
" Complete quickreferenceappendices
onMotiffunc- " Newpanelitemssuchasmultilinetextitemsanddrop
tions,widgets,
andgadgets targetitemshavebeenincluded.ThePanels chapter
This
onebook
canserve
both
yourtutorial
andrefer- has
been
reworked
toclarify
andsimplify
panel
usage
ence
needs.
Thebookassumes
competence
withtheC " Panel
itemextensions
arenowcovered
inXView
programming
language,
aswellasfamiliarity
withfun- Internals
items
toallow
programmers
tobuildcustom
pane
damental
XWindow
System
concepts.
TheMotif
Programming Manual^notonlythemostcomprehen- TheAttribute Summary fromtheprevious
edition
ofthe
siveguidetowritingapplications
withMotif,it isan XViewProgramming
Manual'hasbeenexpandedand
integral
partofthemost widelyusedseries
ofbooks on isnowpublished
asa companionvolume,
theXView
Reference
Manual.It contains
complete
alphabetical
listingsof all XViewattributes,functions,and macros,as
well as other reference information essential for XView
VolumeSix Volume Seven programmers.

XViewProgrammingManual:
798pages,ISBN:0-937175-87-0
-1^ -"" "
Motif Programming XView Programming XViewReference
Manual:
Manual Manual 266pages,ISBN:0-937175-88-9
XViewProgrammingand ReferenceManual Set:
1064pages,ISBN:0-937175-89-7

SENDE-MAIL
QUESTIONS
[email protected]
ORUUHET'.OKA'.NUTS
Volume8: X WindowSystem " HowtousePCandMacXservers
tomaximize
reuse
Administrator's Guide for X11 of existinghardwareand convertoutdatedhardware
Release4 and Release5 intoXterminals
" Howto obtainand installadditionalpublic domain
By LindaMui and EricPearce
softwareand patchesfor X
1stEdition, October1992
" Coversfeaturesnewin R5,includingthefont server
As X moves out of the hacker's domain and into the and Xcms
"real world," userscan't beexpectedto masterall the
TheX WindowSystemAdministrator's Guideis avail-
ins andoutsof settingup and administeringtheir own X
ableeitheraloneor packagedwith theX CD. TheCD
software.Thatwill increasinglybecomethedomainof
will provideX sourcecodeto complementthe instruc-
systemadministrators.Evenfor experiencedsystem
tionsfor installingthe software.
administratorsX raisesmanyissues,both becauseof
subtle
changes
inthestandard
UNIX
way
ofdoing
things Without
CD-ROM,
372pages,
ISBN:
0-937175-83-8
and becauseX blurs the boundaries between different WithCD-ROM,ISBN:1-56592-052-X

platforms.
Under
X,users
canrunapplications
across X WindowSystem
thenetwork,onsystems
withdifferent
resources Administrator's Guide CD-ROM
(including
fonts,
colors,
andscreen
size)thanthe TheCD-ROM
contains
thesource
codeforMIT's
applications
weredesigned
fororiginally.
Manyof publicdomain
XWindow
System,
andwillbeoffered
these issues
arepoorly
understood,andthetechnology withtheXWindow
System's
Administrator's
Guide.
It
fordealingwiththem
isinrapidflux.This
bookisthe contains
pre-compiled
binaries
forpopular
platforms,
firstandonlybookdevoted
totheissues
ofsystem andcomes complete
withaninstallation
system
that
administration
forX andX-based
networks,
written
not allows
custom
installation
oftheCD-ROM.
justforUNIX
systemadministrators
butforanyone TheCDincludes:
facedwiththejobof administering
X (including
those " RockRidgeCD-ROMdriversfromYoungMinds,so
running
Xonstand-alone
workstations). youcaninstall
theCDasaUNIX
filesystem
onseveral
Thebook includes: popular UNIXplatforms.
" Anoverviewof X that focuseson issuesthat affectthe " Complete"core" sourcefor MITXI1 Release4 and 5.
system
administrator's
job Thisincludes
thenewR5features,
suchasthe
" Information
onobtaining,
compiling,
andinstalling fontserver
andXCMS.
theXsoftware,
including
a discussion
of thetrade-offs " Complete "contrib"sourcefor MITXI1 Release5.
between
vendor-supplied
andthefreeMITversions
ofX Thisincludessomeprograms notavailable
in theMIT
" Howtosetupxdm, theXdisplay
manager,
which distribution,
such
as'xtici',theTektronics
Color
takes
theplaceoftheloginprogram
under
Xandcan Editor.
beusedto createa customized
turnkey
X session
for " Complete
examples
andsourcecodefor all thebooks
eachuser in theX WindowSystemSeries.
" Howto setupuseraccounts underX (includes a " Programs andfilesthatarediscussedin Volume 8.
comparison of thefamiliarshellsetupfilesandpro- These werepreviouslyavailable
onlyto administrators
gramsto thenewmechanisms provided byX) withInternetaccess.
" Issues
involved in makingX moresecure. X'ssecurity " Pre-compiledXI1 Release5 binariesfor Sun3,Sun4,
featuresarenotstrong,butanunderstanding ofwhat andIBMRS6000 platforms.(TheRS6000 serversup-
featuresareavailablecanbeveryimportant, sinceX portstheSkyway adaptor,not
makes it possible
for userstointrudeoneachother thenewGT3adaptor.)
in newand sometimes
unexpectedways.
" HowfontsareusedbyX,including
adescription
of Volume
Eight
the font server
" Adiscussion
of theissues
raisedbyrunningXonhet-
erogenousnetworks X Window System
" Howcolors are managedunder X and how to get the Administrator's
Guide
samecolorsacrossmultipledeviceswith different
hardware characteristics
" Theadministrationissuesinvolvedin settingupand
managing
X terminal
O'Reilly
&Associates,
liv

ORDERTOLL-FREE
IN US/CANADA, YAM- SPMPST, 1-800-998-9938
 Programmer's
Supplement
forR5of the TheX WindowSystemin a Nutshell
X WindowSystem,Version11 Edited
byEliteCutler,
DanielGilly,andTim0[Reilly
By DavidFlanagan 2nd Edition,April 1992
1stEdition,November
1991 Onceprogrammers
havemastered
theconcepts
behind
Thisbookisforprogrammers
whoarefamiliar
with Xandlearned
howto program
inXlibandXtthereis
Release
4 of theXWindowSystemandwantto know stillamassofdetailsto remember. TheX Window
howto usethenewfeatures
of Release
5. It is intended System in a Nutshellfillsthisgap.Experienced
Xpro-
asanupdate
forowners
ofVolumes1,2,4,and5ofthe grammers
canusethissingle-volume
desktopcompan-
O'Reilly
andAssociates'
XWindow System
series,
and ionformostcommon questions,
keepingthefullX
provides
complete
tutorial
andreference
information
to WindowSystemseries
ofmanuals
fordetailed
refer-
all new Xlib andXt toolkit functions. ence. X in a Nutshellcontainsessentialinformationin a
It includes: boiled-down
quick-reference
format
thatmakes
it easy
" Overview
oftheR5changes
asthey
affect
applicationtofindtheanswers
needed
most
often:
programming " Command
lineoptions
andresources
forthestandard
" How
towrite
aninternationalized
application-one MITXclients
thatanticipates
theneeds
ofalanguage
andculture " Calling
sequence
forallXlibandXtfunctions
andmacros
otherthanEnglish " Detailed
descriptionof structures,enums,and otherX
" Howtousescalable
fontsandthefontsprovided
by datatypes
used
asarguments
orreturnvalues
inXlib
thenewfont server or Xt functions
" Howtogetconsistent
coloronanydisplay
byusing " Description
ofthecodeinside
abasic
widgetquick
theXColorManagement
System reference
totheevent
structures
" Overview
ofPEX,thenewthree-dimensional
graphics " Fontnamesyntax,
colornames,
resource
fileand
extensionfor X translationstablesyntax,and cursors
" Reference
pages
for allnewandmodified
XlibandXt " XlibandXterrormessages
functions
andAthena
widgets Thisbookhasbeen
newly
updated
tocover
R5butis
TogetherwithVolume2 andVolume5, ownersof the still usefulfor R4. Thedescriptionsof thefunctions
Programmer'sSupplementfor Release5 havea com- havebeenexpandedand clarified,with improvedcross-
pletesetof reference
pages
for thecurrentMITX referencing
to important
relatedfunctions.
Includes
Consortium standards for Xlib and Xt. material on Xcms and the internationalization features

390pages,
ISBN:
0-937175-86-2 ofR5.
424pages,ISBN:1-56592-017-1

R5 Update

Programmer'sSupplement
for Release
5

SENDE-MAILQUESTIONS
[email protected]
ORUUHEJ'.OM'.HUTS
PHIGSProgrammingManual: 3D Whether
youarestarting
outin3Dgraphics
program-
Programmingin X mingorarea seasoned
veteran
looking
foranauthori-
ByTom
Goskins tative
work
onafast-rising
3Dgraphics
standard,
this
1stEdition,
February
1992 bookwillserve
yourpurposes
well.
Acomplete
andauthoritative
guide
toPHIGS
andPHIGS Softcover:
968pages,
ISBN:
0-937175-85-4
PLUS
programming,
thisbookdocuments
thePHIGS Hardcover:
968pages,
ISBN:
0-937175-92-7
andPHIGSPLUSgraphicsstandardsandprovidesfull
guidance
regarding
theuse
ofPHIGS
within
theXenvi- PHIGS
Reference
Manual:
3D
ronment.
Thediscussions
ofPHIGS
andPHIGS
PLUS Programmingin X
are fully integratedin this text,which takesasits start- Editedby Linda Kosko
ingpointthePEX
Sample
Implementation
(orPEX- 1stEdition,
October
1992
SI)-the publicly availableand mostwidelyestablished Thedefinitiveand exhaustive
referencedocumentation
basefor commercial
PHIGS products.In addition,
the for thePHIGS/PEX Sample Implementation
("PEX-SI").
PHIGS Programming Manualexplains, at bothelemen- Containsall thereferencepages
fromtheMITX
taryandadvancedlevels,
howto integrateyourPHIGS Consortium release,
butin upgraded
form,withaddi-
applications
withstandard X (Xh'b)functions.
Window tionalreference materials.
Together
withthePHIGS
management,
event
handling,
input-output,
evenlower- Programming
Manual,
thisbookisthemostcomplete
leveldrawing
functions-allof thesecanbemade
part andaccessible
documentation
currently
available
for
of your PHIGSprograms.BesidesXlib itself, thereare boththePEX-SI
andthePHIGS
andPHIGSPLUS
standards.
detailed
examples
andexplanations
based
ontheMotif, The
PHIGS
Reference
Manual
isthedefinitive
and
OLIT,andXView toolkits. exhaustive
reference
documentation
for thePHIGS/PEX
ThePHIGS Programming Manual: SampleImplementation
("PEX-SI").It contains
all the
" Offers
a clearandcomprehensiveintroduction
to reference
pagesfromtheMITXConsortium release,but
PHIGS:
output
primitives,
attributes,
color,structure, inupgraded
form.It alsocontains
additional
reference
andallyouneedto knowto beginwritingPHIGS
pro- materials.
grams
1116pages,ISBN:0-937175-91-9
" Offers technical know-how. Author Tom Gaskins has
for manyyearsbeenanimplementor
of PHIGS
andis
also a key contributorto the internationalPHIGSstan-
dardization efforts.
" Showshow to usePHIGSin your X WindowSystem
applications
" Illustrates
theconcepts
of PHIGS
andPHIGS
PLUS
with over 200 figures
" Clearlyexplainsthe subtletiesof viewing,lighting,and
shading,completewith practicalcodeexamples,each
of themmodularand simpleto understand,but virtu-
ally noneof themmerelya "toy" program
" Includesthe DISISOCbinding,the closestin exis-
tenceto thecomingISOstandard
" Demonstrates the use of PHIGS and PHIGS PLUSin
interactiveprograms,so that youcando morethan
merelydisplaypictures
" Fullydescribesall the PHIGSand PHIGSPLUS
functions
" Hasa companionreferencemanual. Takentogether,
thesebooksare the only documentation
you'll need
for a productthatis changing
thewaytheXworld
thinksaboutgraphics.

ORDERTOLL-FREE
IN US/CANADA, YAM- SPMPST, 1-800-998-9938
PEXlibProgramming
Manual PEXlibReference
Manual
By TomGoskins By0 'Reilly&Associates
1stEdition,December
1992 1stEdition,December
1992
Theworldof workstations
changed dramatically
with ThePEXlib ReferenceManualis thedefinitive
pro-
therelease
of theXWindow System.
Userscanfinally grammer's reference
resourcefor PEXlib,
andcontains
countonaconsistent
interfaceacrossalmost
allmakes complete andsuccinct
referencepagesforah1the
andmodels of computers.Atthesametime,graphics callable
routinesinPEXlib
version5.1. Thecontent of
applications
become easilyportable. thePEXlibReferenceManualstands, withrelatively
few
Until
recently,
Xsupported
only2Dgraphics.
Now, changes,
asitwas
created
bytheMITXConsortium.
however,bymeans of thePEXextensions to Xtogether ThePEXlibReferenceManualis acompanion volume
withthePEXlibapplications
programming interface, to theO'Reilly
andAssociates'
PEXlibProgramming
native,
3Dgraphicshavecometo theXWindow System. Manual,writtenbyTomGaskins.TheProgramming
PEXliballowstheprogrammer to creategraphicspro- Manualis athoroughtutorialguideto PEXlib,
and
gramsof anycomplexity,andalsoprovides thebasisfor includesvaluable
reference
features.Together,
these
higher-level
graphicssystemsandtoolkits. booksofferthemostcomplete andaccessibledocu-
mentation available for PEXlibversion 5.1.
ThePEXlibProgrammingManual is thedefinitivepro-
grammer's
guideto PEXlib,
covering
bothPEXversions 577pages,
ISBN:
1-56592-029-5
5.0 and 5-1. Containingover 200illustrationsand 19
color plates,it combinesa thoroughandgentletutorial
approachwith valuablereferencefeatures.Alongthe
way,it presentsthe readerwith numerousprogram-
mingexamples,aswell asa libraryof helpfulutility rou-
tines-all of which are available online. You do not
needto haveprior graphicsprogrammingexperience
in
order to read this manual.

Writtenby TomGaskins-the widelyrecognized

authority
whoalsoauthored
theO'Reilly
andAssociates'
PHIGSProgramming Manual-this bookis theonly
programmingguideto PEXlibyouwill everneed.
1154'pages,
ISBN:1-56592-028-7

SENDE-MAILQUESTIONS
[email protected]
ORUUHET!ORA!HUTS
About The X Resource The*Resource:
lssue*>
Ju'y1992
EditedbyAdrian Nye
TheX Resource
is aquarterly
workingjournalfor X
Tableof Contents,
Issue3 (Juty1992):
programmersthatprovidespractical,timelyinforma-
tionabouttheprogramming,
administration,
anduse DEPARTMENTS
of theXWindow System.
TheXResourceis theOfficial " XtPerformance
Improvements
in Release
5,
Publisherof theMITX Consortium
TechnicalConference by GabeBeged-Dov
Proceedings,
whichformtheJanuary
issue.
Issues
can " TheX User:MakingBetterUseof Resources,
bepurchased
separately
or bysubscription. byPaul
Davey
" TheX Administrator:ManagingFontServers,
TheXResource:
Issue2, April1992 byEric
Pearce
" Bestof NetworkNews,editedbyMarcAlbert
Editedby AdrianNye
PAPERS
Tableof Contents,Issue2 (April 1992):
" Multi-userApplicationSoftwareUsingXt,
DEPARTMENTS:
by OliverJones
" FromtheX Consortium:CurrentProjects,by Bob " AnExtension
for Server
Instrumentation
andTracing,
Scheifler
byMarkJ. Kilgard
" Bestof Netnews,
editedby MarcAlbert " Usingthe NewFontCapabilitiesof HP-donated
Font
" The
XUser:
Designing
forUsability,
byScott Server
Enhancements,
byAxel
Deininger
and
McGregor Nathan
Meyers
" TheXAdministrator:
FontFormats
andUtilities,
by " Improving
XApplication
Performance,
byChris
D.
Dinah
McNutt
andMilesO'Neal Peterson
andSharon
E.Chang
PAPERS: " ARulerModelfor theMotifFormWidget,
byThomas
" NASA's
TAB PLUS:
a GUIDevelopment
Tooland Berlage
Application
Environment,
byMartiSzczur " ANewParadigm
for Cross-platform
Automated
GUI
" Understanding
GrabsandKeyboard
Focus,
byWayne Testing,
byLawrence
R.Kepple
Dyksen DOCUMENTATION
" Designing
Reusable
Widget
Classes
withC++and " The
Nonrectangular
Window
Shape
Extension,
by
OSF/Motif,
byAndreas
Baecker Paula
M.Ferguson
" Visualizing
X,byDavid
Lemke
andDavid
Rosenthal " Public-domain
XcRichText
Widget,
byDanConnolly
" imake
Demystified,
byPaulDavey 220pages,
ISBN:
0-937175-98-6
DOCUMENTATION:

" Wcl 2.0: TheWidgetCreationLibrary

190pages,ISBN:0-937175-97-8

ORDERTOLL-FREE
IN US/CANADA, 7AM - 5PM PST, 1-800-998-9938
TheX Resource: Issue4, October1992 TheX Resource: Issue5, January1993
Edited
byAdrian
Nye Edited
byAdrian
Nye
Tableof Contents,
Issue4 (October
1992): Tableof Contents,
Issue5 (January
1993):
FROMTHEEDITOR FROMTHE EDITOR
" 7thAnnualXTechnical
Conference " Proposal
for anX-based
OnlineHelpProtocol,
" Xhibition
93Conference:
CallforParticipation byKent
J.Summers
andJeffrey
L.Vogel
" TheXResource
Code
Archive " Describing
Formats
forX-based
DataInterchange,
by Ellis S.Cohen
DEPARTMENTS
" From The X Consortium: The MIT X Software " AWidget ClassExtension
for ImprovedGeometry
Management, bySteveHumphrey
DistributionAfterRelease5, by StephenGildea,MITX
Consortium " TheLayoutWidget: ATeX-StyleConstraint
Widget
Class,
byKeithPackard
" TheX Administrator:TamingtheX DisplayManager,
by MilesO'Neal " BuildingDistributed
UserInterfaces
withFresco,
by MarkLintonandChuckPrice
" X UserGroups
" Melding
OSF/Motif,
C++andtheIntrinsics,
" ThePEXInteroperability
Center,
byKathyHarris
byDouglas
S.RandandGillesBenati
PAPERS " TheTrestle
Toolkit,
byMarkS.Manasse
" Finding
Auxiliary
Files
foranXToolkit
Application,
by " Hypergraphics
andHypertext
inTk,byJohn
K.
DavidFlanagan Ousterhout
" RPC
Programming
inXApplications,
byJohn
Bloomer " The
XEngine
Library:
AC++Library
forConstructin
" ABibliography
ofWindowing
Systems
andSecurity,
by X Pseudo-servers,
byJohnMenges
Jeremy
Epstein " TheX FileSystem,
byJeffNisewanger
" TheXGEN
Application
Generator:
Constructing
Motif " Trace
Analysis
oftheXWindow
System
Protocol,
GUIsForTTYPrograms,by Kurt Buehler by LaurenceP. G.Cableand StuartW.Marks
" WorkstationAudioin theX Environment,
by Richard " Multi-threadedXlib, by StephenGildea
Billman,RobertHammond,PatMcElhatton,Ellen
" DistributedMemoryMulti-computersasX Clients,
Nordahl
Brandt,
Francis
Sung,
andNancy
Yost
bySteveR.Ball and ChrisW.Johnson
DOCUMENTATION
" GUIfor Near-Real-Time
Applications
in X-
" A Directoryof FreelyandCommercially
Available Programming
Tips,by Ilan Aisic
Widgets
" TaX:AToolfor BuildingTimeDependent
" The
Cmap
Widget Applications,
byNunoM.Correia
andNuno
M.
" TheHdialWidget Guimaraes
" The
XI1InputExtension:
ATutorial,
byPaula " Supporting
Mobile,
Pen-based
Computing
with
X,
Ferguson byJames
Kempf
andAlan
Wilson
" The
XI1InputExtension:
Reference
Pages " Making
theXWindow
System
Accessible
toPeople
276pages,
ISBN:
0-937175-99-4 withDisabilities,
byWillD.WalkerandMarkE.Novak
" Runtime Translation
ofX Interfaces
to Support
Visually-Impaired
Users,
byKeithEdwards and
Thomas Rodriguez
" AFullyFunctionalImplementationof Layered
Windows,by PeterDaifuku
THE X RESOURCE
" AnUpdate
onLow-Bandwidth
X (LBX),byJimFulton
272pages,ISBN:1-56592-020-1

SENDE-MAIL
QUESTIONS
[email protected]
ORUUNET!ORA!NUTS
 - - '
E
^j "- " .- xi ^ _ v-' 1 "i 0
= 2i i - c;=| ^ y: cl
C
^f.1 I,,-f ' 1^ 1f g"1 1= s
s £

^ -Sc ^ '<-.i t: 5 * ^ "<.> .5;-s ^ "^ |

>, 5 "§ .=""£"$ £ c_pr ^ -cL
"§"§"« '
~
5 S c' .§^' .§:"a c.>.^. *_^ 7" 'S~. %
.2 <uc w s S '<.' ^ - 6 ^ S 'S, ^ 2 -\
H. ~ - £ $ ^ 5 -"/-^ _5 $ "^55 1 i^
u ° S '^ i: ^ -< -^ 2 c '-^ $ S * \C
'f< "dL"- .9" " ^ -?" ^ tr! *"* *^ 5 i x J

'"^ | | = i | | S^ "I §
~~ - "" ^j "^;
a 1
v. *"" p\ ""* -^ ^ "5 i X ^ z
z 2
"" c -z.' ^ ^ ^ ~Z^ ~^"- - i ^ ^ £ i 5
' t" "^* ^" ^o~^'~S -T -i ~1 - r- ."v -
"^ C "^2 CJ - ~" "^ - '> - 13 ^! 'r~
~. ? ^ N 5 "g E!
^- ~^~ -^ ^-
" f- f- ^3
'^1 ^-/
-V t7? ,^ o "*r ^/ - 7 "- ^ C y. , ^ >- ^ i- 7 2
''-
" "^ -~ r~ '>- X^ :? "= - s. i- .- <
x>" "i= pn _3 ^3 ^ i ~ ^ g £ _ _ ~) Ej 7 /
O -5 :- /" ^ [j c ± ^ / 7.

\ Books
That
Help
People
GetMore
OutofComputer
I
If you want more information about our
Name.
books, or want to know where to buy them,
we're happy to send it. Address.
a Send me a free catalog of titles.

3 What bookstores in my area carry your

books(U.S.and Canadaonly)?
City_
a Where can I buy your books outside the
U.S.and Canada? State, ZIP

3 Send me information about consulting

Country-
services for documentation or program-
ming. Phone
a Send me information about bundling
bookswithmyproduct. EmailAddress.
NAME NO POSTAGE

COMPANY_ NECESSARY IF
MAILED IN THE
ADDRESS_
UNITED STATES
CITY STATE ZIP

BUSINESS REPLY MAIL

FIRST CLASS MAIL PERMIT NO. 80 SEBASTOPOL,CA

POSTAGE WILL BE PAID BY ADDRESSEE

O'Reilly & Associates, Inc.

103 Morris Street Suite A
Sebastopol CA 95472-9902

NAME

COMPANY

ADDRESS

CITY STATE ZIP

BUSINESS REPLY MAIL

FIRSTCLASSMAIL PERMITNO.80 SEBASTOPOL,
CA

POSTAGEWILL BE PAID BY ADDRESSEE

O'Reilly & Associates, Inc.

103 Morris Street Suite A
Sebastopol CA 95472-9902
 Overseas Distributors

Effective January 1, 1990,customersoutside the U.S. and Canadawill be able to

order O'Reilly & Associatesbooksthroughdistributorsnearthem. Theseoverseas
locations offer international customers faster order processing, more local
bookstores and local distributors, and increased representation at trade shows
worldwide, as well as the high level, quality service our customers have always
received.

AUSTRALIA & NEW ZEALAND LATIN AMERICA (inquiries)

(orders and inquiries) Addison-Wesley Iberoamericana S.A.
Addison-Wesley Publishers, Pty. Ltd. Blvd. de las Cataratas No. 3
6 Byfield Street Colonia Jardines del Pedregal
North Ryde, N.S.W. 2113 Delegacion Alvaro Obregon
AUSTRALIA Mexico 01900, D. F.
Telephone: 61-2-888-2733 MEXICO
FAX: 61-2-888-9404 Telephone: 525-660-2497
FAX: 525-660-4930
GREAT BRITAIN & AFRICA

(orders and inquiries) LATIN AMERICA (orders)

Addison-Wesley Publishers Ltd. Addison-Wesley Publishing Company
Finchampstead Road International Order Department
Wokingham, Berkshire RG11 2NZ Jacob Way
ENGLAND Reading, MA 01867 U.S.A.
Telephone: 44-734-794-000 Telephone: 1-617-944-3700
FAX: 44-734-794-035 FAX: 1-617-942-2829

EUROPE & MIDDLE EAST ASIA except JAPAN (inquiries)

(orders and inquiries) Addison-Wesley (Singapore) Pte. Ltd.
Addison-Wesley Publishing Group 15 Beach Road
Concertgebouwplein 25 05-09/10 Beach Centre
1071 LM Amsterdam SINGAPORE 0718

THE NETHERLANDS Telephone: 65-339-7503

Telephone: 31-20-671-72-96 FAX: 65-339-9709
FAX: 31-20-664-53-34

ASIA except JAPAN (orders)

U.S. & CANADA Addison-Wesley Publishing Company
(orders and inquiries) International Order Department
O'Reilly & Associates, Inc. Jacob Way
103 Morris Street, Suite A Reading, MA 01867 U.S.A.
Sebastopol, CA 95472 U.S.A. Telephone: 1-617-944-3700
Telephone: 1-800-338-6887 FAX: 1-617-942-2829
Fax: 1-707-829-0104
JAPAN (orders and inquiries)
Toppan Company, Ltd.
Ochanomizu Square B, 1-6
Kanda Surugadai
Chiyoda-ku, Tokyo 101
JAPAN

Telephone: 81-3-3295-3461
FAX: 81-3-3293-5963
 mdow System Administrator's Guidi
As X moves out of the hacker's domain and into the "real world," users can't be expected to
master all the ins and outs of setting up and administering their own X software. That will
increasingly become the domain of system administrators. Even for experienced system
administrators X raises many issues, both becauseof subtle changes in the standard UNIX way
of doing things and because X blurs the boundaries between different platforms. Many of these
issues are poorly understood, and the technology for dealing with them is in rapid flux.

X Window System Administrator's Guide is the first and only book devoted to the issues of
system administration for X and X-based networks, written not just for UNIX system
administrators but for anyone faced with the job of administering X (including those running X
on stand-alone workstations). The book includes:

An overview of X that focuses on issues that affect the system administrator's job
Information on obtaining, compiling, and installing the X software, including a discussion
of the trade-offs between vendor-supplied and the free MIT versions of X
How to set up xdm, the X display manager, which takes the place of the login program
under X and can be used to create a customized turnkey X sessionfor each user
How to set up user accounts under X
The issues involved in making X more secure
How fonts are used by X, including a description of the R5 font server
A discussion of the issues raised by running X on heterogenous networks
How colors are managed under X and how to get the same colors across multiple devices
with different hardware characteristics.

The administration issues involved in setting up and managing X terminals.

How to use PC and Mac X servers to maximize reuse of existing hardware and convert
outdated hardware into X terminals

How to obtain and install additional public domain software and patches for X.
Covers features new in R5, including the font server and Xcms.

ISBN 0-937175-83-f
90000>

Printed on Recycled Pa,

9 II780937II1 75835 Book alone: ISBN 0-937175-83-8

Book with CD: ISBN 1-56592-052-X

O'Reilly & Associates, Inc.

**-. ***
J^Wffc
£*<$£&£><
"fttyte
«**«**
<%m- \^/^
v ;
m
£SK
^?*<v "
?*Vi
«*.v-t -/;i
X*
fc:
:"
""M-'
'
H.'

"".-

r»M'l-»
:*^i
/>?;<
-^ i1.
. *V*-

IJU ;,^,
ft;V/-^
r\*>:»**$?¥
X^/^?>'i*
V^-'V*f^

"^sjr1 /, »*>v%
;f>*i
.*"/-;
.»,
'$
 .
-

£&
-

> »~v » -ip. T*^ is

.
:

" " -
'

t'~''I-'-'
- *. *. >

" -
OP*/ "

.
"