Preface

About This Manual

This manual describes the X library, the C Language programming interface to Version 11 of the X Window System. The X library, known as Xlib, is the lowest level of programming interface to X. This library enables a programmer to write applications with an advanced user interface based on windows on the screen, with complete network transparency, that will run without changes on many types of workstations and personal computers.

Xlib is powerful enough to write effective applications without additional programming tools, and is necessary for certain tasks even in applications written with higher-level “toolkits.”

There are a number of these toolkits for X programming, the most notable being the DEC/MIT toolkit Xt, the Andrew toolkit developed by IBM and Carnegie-Mellon University, and the Interviews toolkit from Stanford. These toolkits are still evolving, and none of them is currently part of the X standard, although Xt is being considered for inclusion. Toolkits simplify the process of application writing considerably, providing a number of widgets that implement menus, command buttons, and other common features of the user interface.

This manual does not describe Xt or any other toolkit. Our intention is to provide complete documentation of the Xt toolkit in a future volume of our X Window System series. Nonetheless, all the material described in this book is essential for understanding and using the toolkits since the toolkits themselves are written using Xlib.

In Release 1 of Xlib, the resource manager (for parsing the command line and merging user preferences) was a separate library, which had been developed as part of the Xt toolkit. As of Release 2, parts of the resource manager have been incorporated into Xlib. This volume documents the Release 2 resource manager. This manual also describes the X11 routines that were provided for compatibility with X Version 10, chiefly in Volume One, Appendix B, X10 Compatibility.

Summary of Contents

This manual is divided into two volumes. This is the second volume, the Xlib Reference Manual. It includes reference pages for each of the Xlib functions (organized alphabetically), a permuted index, and numerous appendices and quick reference aids.

The first volume, the Xlib Programming Manual, provides a conceptual introduction to Xlib, including tutorial material and numerous programming examples. Arranged by task or topic, each chapter brings together a group of Xlib functions, describes the conceptual foundation they are based on, and illustrates how they are most often used in writing applications (or in the case of the last chapter, window managers). Volume One is structured so as to be useful as a tutorial and also as a task-oriented reference.

Volume One and Volume Two are designed to be used together. To get the most out of the examples in Volume One, you will need the exact calling sequences of each function from Volume Two. To understand fully how to use each of the functions described in Volume Two, all but the most experienced X “hacker” will need the explanation and examples in Volume One.

Both volumes include material from the original Xlib and X11 Protocol documentation provided by MIT, as well as from other documents provided on the MIT release tape. This volume is based heavily on these sources, although it has also been extensively edited and added to. We have done our best to incorporate all of the useful information from the MIT documentation, to correct code references we found to be in error, to reorganize and present it in a more useful form, and to supplement it with conceptual material, tutorials, reference aids, and examples. In other words, this manual is not only a replacement, but is a superset of the MIT documentation.

Those of you familiar with the MIT documentation will recognize that each reference page in this volume includes the detailed description of the routine found in Gettys, Newman, and Scheifler's Xlib–C Language X Interface, plus in many cases additional text that clarifies ambiguities and describes the context in which the routine would be used. We have also added cross-references to related reference pages and to where additional information can be found in Volume One.

How to Use This Manual

Volume Two is designed to make it as easy and fast as possible to look up virtually any fact about Xlib. It includes a permuted index, reference pages for each library function, appendices that cover macros, structures, function groups, events, fonts, colors, cursors, keysyms, and errors, and at-a-glance tables for the graphics context and window attributes.

The permuted index is the standard UNIX way of finding a particular function name given a keyword. By looking up a word in the second column that you think describes the function you are looking for, you can find the group of functions that have that word in their description lines. The description line also appears at the top of each reference page. Once you have found the routine you are looking for, you can look for its reference page.

The reference pages themselves provide all the details necessary for calling each routine, including its arguments, returned values, definitions of the structure types of arguments and returned values, and the errors it may generate. Many of the pages also give hints about how the routine is used in the context of other routines. This is the part of this volume you will use the most.

Appendix A, Function Group Summary, groups the routines according to function, and provides brief descriptions. You'll find it useful to have in one place a description of related routines, so their differences can be noted and the appropriate one chosen.

Appendix B, Error Messages and Protocol Requests, describes the errors that Xlib routines can generate. When an error is handled by the default error handler, one of these messages is printed. Also printed is the X Protocol request that caused the error. Since Protocol requests do not map directly to Xlib routines, this appendix provides a table with which you can find out which Xlib routine in your code caused the error.

Appendix C, Macros, describes the macros that access members of the Display structure, classify keysyms, and convert resource manager types.

Appendix D, The Color Database, presents the standard color database. The color names in this database should be available on all servers, though the corresponding RGB values may have been modified to account for screen variations.

Appendix E, Event Reference, describes each event type and structure, in a reference page format. This is an invaluable reference for event programming.

Appendix F, Structure Reference, describes all structures used by Xlib except the event structures described in Appendix E, including which routines use each structure.

Appendix G, Symbol Reference, lists in alphabetical order and describes all of the symbols defined in Xlib include files.

Appendix H, Keysyms, lists and describes each character in the standard keysym families, used for translating keyboard events. The characters for English and foreign language keysyms are shown where possible.

Appendix I, The Cursor Font, describes the standard cursor font, including a illustration of the font shapes.

Appendix J, Fonts, lists the standard fonts, gives a table of their metrics, and provides an illustration of each font.

Appendix K, Xlib Release 3 Update, describes changes to Xlib in Release 3.

Finally, Volume Two concludes with at-a-glance charts that help in setting the graphics context (GC) and the window attributes.

Assumptions

Readers should be proficient in the C programming language and should have read most of Volume One, Xlib Programming Manual. In addition, general familiarity with the principles of raster graphics will be helpful.

Font Conventions Used in This Manual

Italics are used for:

• UNIX pathnames, filenames, program names, user command names, and options for user commands

Typewriter Font is used for:

• Anything that would be typed verbatim into code, such as examples of source code and text on the screen
• The contents of include files, such as structure types, structure members, symbols (defined constants and bit flags), and macros
• Xlib functions

Italic Typewriter Font is used for:

• Arguments to Xlib functions, since they could be typed in code as shown but are arbitrary

Helvetica Italics are used for:

• Titles of examples, figures, and tables

Boldface is used for:

• Chapter and section headings

Related Documents

The C Programming Language by B. W. Kernighan and D. M. Ritchie

The following documents are included on the X11 source tape:

Xt Toolkit Intrinsics, by Joel McCormack, Paul Asente and Ralph Swick

Xt Toolkit Widgets, by Ralph Swick and Terry Weissman

Xlib–C Language X Interface, by Jim Gettys, Ron Newman, and Robert Scheifler

The following book on the X Window System from O'Reilly and Associates, Inc., is currently in its second printing:

Volume Three —X Window System User's Guide

Two more books on the X Window System are now being developed at O'Reilly & Associates, Inc., and are expected to be published in the Summer of 1989:

Volume Four — Xt Toolkit Programming Manual

Volume Five — Xt Toolkit Reference Manual

Requests For Comments

Please write to tell us about any flaws you find in this manual or how you think it could be improved, to help us provide you with the best documentation possible.

Our U.S. mail address, e-mail address, and phone number are as follows:

O'Reilly & Associates, Inc.

632 Petaluma Avenue

Sebastopol, CA 95472

(800) 338-6887

Licensing Information

This manual has been designed for licensing and customization by manufacturers or distributors of systems supporting X11. As of this writing, it has been licensed by Masscomp, Motorola, Apollo Computer, Silicon Graphics, and Stellar Computer. For information on licensing, call O'Reilly & Associates, Inc. at (800) 338-6887, or send e-mail to [email protected].

Acknowledgements

The information contained in this manual is based in part on Xlib–C Language X Interface, written by Jim Gettys, Ron Newman, and Robert Scheifler, and the X Window System Protocol, Version 11, by Robert Scheifler (with many contributors). The X Window System software and these documents were written under the auspices of Project Athena at MIT. In addition, this manual includes material from Oliver Jones' Xlib tutorial presentation, which was given at the MIT X Conference in January 1988, and from David Rosenthal's Inter-Client Communication Conventions Manual.

I'd like to thank the people who helped this book come into being. It was Tim O'Reilly who originally sent me out on a contract to write a manual for X Version 10 for a workstation manufacturer, and later to another company to write a manual for X Version 11, from which this book began. I've learned most of what I know about computers and technical writing while working for Tim. For this book he acted as an editor, he helped me reorganize several chapters, he worked on the Color and Managing User Preferences chapters when time was too short for me to do it, and he kept my spirits up through this long project. While I was concentrating on the details, his eye was on the overall presentation, and his efforts improved the book enormously.

This book would not be as good (and we might still be working on it) had it not been for Daniel Gilly. Daniel was my production assistant for critical periods in the project. He dealt with formatting issues, checked for consistent usage of terms and noticed irregularities in content, and edited files from written corrections by me and by others. His job was to take as much of the work off me as possible, and with his technical skill and knowledge of UNIX he did that very well.

This manual has benefitted from the work and assistance of the entire staff of O'Reilly & Associates, Inc. Susan Willing was responsible for graphics and design, and she proofed many drafts of the book; Linda Mui tailored the troff macros to the design by Sue Willing and myself, and was invaluable in the final production process; John Strang figured out the Release 2 resource manager and wrote the section on that topic; Karen Cakebread edited a draft of the manual and established some conventions for terms and format. Peter Mui executed the “at-a-glance” tables for the inside back cover; Tom Scanlon entered written edits and performed copy fitting; Linda Walsh updated the index of the book; Valerie Quercia, Tom Van Raalte, and Donna Woonteiler all contributed in some small ways; and Cathy Brennan, Suzanne Van Hove, and Jill Berlin fielded many calls from people interested in the X manual, and saved me all the time that would have taken. A special thanks to everyone at O'Reilly & Associates for putting up with my habits of printer and terminal hogging, lugging X books around, recycling paper, and for generally being good at what they do and good-natured to boot.

I would also like to thank the people from other companies that reviewed the book or otherwise made this project possible: John Posner, Barry Kingsbury, and Jeffrey Vroom of Stellar Computer; Oliver Jones of Apollo Computer; Sam Black, Jeff Graber, and Janet Egan of Masscomp; A1 Tabayoyon, Paul Shearer, and many others from Tektronix; Robert Scheifler and Jim Fulton of the X Consortium (who helped with the Color and Managing User Preferences chapters), and Peter Winston II and Aub Harden of Integrated Computer Solutions. Despite the efforts of the reviewers and everyone else, any errors that remain are my own.

—Adrian Nye