www.sbin.org

[PreviousSection] [Back to Table of Contents] [Next Section]

Xlib Programming Manual (O'Reilly & Associates, Inc.)

Sources of Additional Information

This appendix describes where you can get more information about Xlib and about X in general, including other books on the subject and the various ways to get the source code for X.

This appendix lists a few of the official and unofficial sources for information about the X Window System and associated software.

Note that some of this detailed information may become dated rather quickly. The best source of current information is the comp.windows.x network news group, described later in this appendix.

Getting the X Software

At this writing, the current public release level is Release 5. This book documents Release 4 and Release 5. Many people will continue to use R4 for a while, since there is a considerable lag time between the date that MIT distributes a new release and the date by which vendors integrate that release into their own products and issue updates. All changes to Xlib in R5 are backwards compatible, although there are many new interfaces that provide additional capabilities.

You can get the X software directly from MIT on three 9-track 1600-BPI magtapes written in UNIX tar format or on one 9-track 6250-BPI magtape, along with printed copies of MIT's manuals, by sending a check in U.S. currency for U.S. $400 to:

MIT Software Distribution Center
Technology Licensing Office
MIT E32-300
77 Massachusetts Avenue
Cambridge, MA 02139

Their telephone number is (617) 253-6966, and the "X Ordering Hotline" is (617) 258-8330. If you want the tapes and manuals shipped overseas, the price is $500. The manual set alone is $125, including U.S. shipping, or $175, including overseas shipping.

Other distribution media or formats are not available from the MIT Software Distribution Center but are from other independent vendors such as ICS, mentioned later. The Release tape comes with source code for sample servers for Apollo, DEC, HP, IBM, Sony, Sun, and several other workstations, source code for clients written by MIT, sources for the toolkits Xt, XView, Interviews, and Andrew, contributed software written outside MIT, and sources and Postscript files for all MIT's documentation. Note that the servers supplied are sample servers only; commercial vendors typically release optimized (faster) servers for the same machines.

Sites that have access to the Internet can retrieve the distribution from the following machines using anonymous ftp. Here are the current sites:
Table G-1 : X Software Sites
Location Hostname Address Directory
Western USA gatekeeper.dec.com 16.1.0.2 pub/X11/R5
Eastern USA ftp.uu.net 192.48.96.9 X/R5
137.39.1.9 X/R5
Northeastern USA export.lcs.mit.edu 18.24.0.12 pub/R5
crl.dec.com 192.58.206.2 pub/X11/R5
Central USA mordred.cs.purdue.edu 128.10.2.2 pub/X11/R5
giza.cis.ohio-state.edu 128.146.8.52 pub/X.V11R5
Southern USA wuarchive.wustl.edu 129.252.135.4 packages/X11R5
UK (Janet) src.doc.ic.ac.uk 146.169.2.1 X
Australia munnari.oz.au 128.250.1.21 X.V11/R5
192.43.207.1 X.V11/R5
 

DO NOT do anonymous ftp during normal business hours, and please use the machine nearest you.

The distribution is also available by UUCP from UUNET for sites without Internet access. The files are split up to be small enough for UUCP distribution.

Bug Fixes

Critical bug fixes as well as a limited number of important new features are available from the archive server xstuff@expo.lcs.mit.edu. Electronic mail sent to this address is forwarded to a program which responds with the requested information. The rest of this section and the two sections that follow it explain how to use xstuff.

The xstuff server is a mail-response program. This 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 do not send it commands that it understands, it will just answer "I don't understand you."

The xstuff server reads your entire message before it does anything, so you can have several different commands in a single message. It treats the "Subject:" header line just like any other line of the message. You can use any combination of upper and lowercase letters in the commands.

The archives are organized into a series of directories and subdirectories. Each directory has an index, and each subdirectory has an index. The top-level index gives you an overview of what is in the subdirectories, and the index for each subdirectory tells you what it contains.

If you are bored with reading documentation and just want to try something, then send the server a message containing the line: 

send index fixes
When you get the index back, it will contain the numbers of all of the fixes and batches of fixes in the archive. Then you can send the server another message asking it to send you the fixes that you want: 
send fixes 1 5 9 11-20
If you are using a mailer that understands "@" notation, send to xstuff@expo.lcs.mit.edu. If your mailer deals in "!" notation, try sending to {someplace}!eddie!expo.lcs.mit.edu!xstuff. For other mailers, you're on your own.

The server has four commands. Each command must be the first word on a line.

help
The command help or send help causes the server to send you the help file. No other commands are honored in a message that asks for help (the server figures that you had better read the help message before you do anything else).
index
If your message contains a line whose first word is index, then the server will send you the top-level index of the contents of the archive. If there are other words on that line that match the names of subdirectories, then the indexes for those subdirectories are sent instead of the top-level index. For example, you can say:
  • index
    • or:
  • index fixes
    • You can then send back another message to the xstuff server, using a send command (see below) to ask it to send you the files whose names you learned from that list.
    index fixes and send index fixes mean the same thing: you can use send instead of index for getting an index.
    If your message has an index or a send index command, then all other send commands will be ignored. This means that you cannot get an index and data in the same request. This is so that index requests can be given high priority.
    send
    If your message contains a line whose first word is send, then the xstuff server will send you the item(s) named on the rest of the line. To name an item, you give its directory and its name. For example:
  • send fixes 1-10
    • Once you have named a category, you can put as many names as you like on the rest of the line. They will all be taken from that category. For example:
  • send fixes 1-10 11-20 21-30
    • Each send command can reference only one directory. If you would like to get one fix and one of something else, you must use two send commands.
    You may put as many send commands as you like into one message to the server, but the more you ask for, the longer it will take to receive. See Section G.1.1.2, "Fairness"" for an explanation. Actually, it is not strictly true that you can put as many send commands as you want into one message. If the server must use UUCP mail to send your files, then it cannot send more than 100K bytes in one message. If you ask for more than it can send, then it will send as much as it can and ignore the rest.
    path
    The path command exists to help in case you do not get responses from the server when you mail to it.
    Sometimes the server is unable to return mail over the incoming path. There are dozens of reasons why this might happen, and if you are a true wizard, you already know what those reasons are. If you are an apprentice wizard, you might not know all the reasons, but you might know a way to circumvent them.
    If you put in a path command, then everything that the server mails to you will be mailed to that address rather than to the return address on your mail. The server host expo.lcs.mit.edu does not have a direct UUCP connection to anywhere; you must go through mit-eddie (the UUCP name of eddie.mit.edu) or somewhere else.

    Notes

    The xstuff server acknowledges every request by return mail. If you do not get a message back in a day or two, you should assume that something is going wrong and perhaps try a path command.

    The xstuff server does not respond to requests from users named root, system, daemon, or mailer. This is to prevent mail loops. If your name is "Bruce Root" or "Jane Daemon" and you can document this, we will happily rewrite the server to remove this restriction. Yes, we know about Norman Mailer and Waverley Root. Norman doesn't use netmail and Waverley is dead.

    Fairness

    The xstuff server contains many safeguards to ensure that it is not monopolized by people asking for large amounts of data. The mailer is set up so that it will send no more than a fixed amount of data each day. If the work queue contains more requests than the day's quota, then the unsent files will not be processed until the next day. Whenever the mailer is run to send its day's quota, it sends the shortest requests out first.

    If you have a request waiting in the work queue and you send in another request, the new request is added to the old one (thereby increasing its size) rather than being filed anew. This prevents you from being able to send in a large number of small requests as a way of beating the system.

    The reason for all of these quotas and limitations is that the delivery resources are finite, and there are many people who would like to make use of the archive.

    Netnews

    The Usenet network newsgroup and mailing lists are probably the most valuable source of information abouta X. The current list of public mailing lists that discuss X is as follows:
    Table G-2 : Netnews Public Mailing Lists
    News Group Description
    motif@alphalpha.com People interested in the OSF's Motif X toolkit This mailing list is also gatewayed to the Usenet newsgroup comp.windows.x.motif . If you receive that newsgroup, you don't need to get this mailing list.
    x11-3D@expo.lcs.mit.edu People interested in X and 3-D graphics
    x-ada@expo.lcs.mit.edu X and ada
    ximage@expo.lcs.mit.edu People interested in image processing and X
    xpert@expo.lcs.mit.edu General discussion of X This mailing list is also gatewayed to the Usenet newsgroup comp.windows.x . If you receive that newsgroup, you don't need to get this mailing list.
    openlook@unify.com Discussion of the OPEN LOOK graphical user interface, and its various implementations. This mailing list is also gatewayed to the Usenet newsgroup comp.windows.open-look . If you receive that newsgroup, you don't need to get this mailing list.
    xvideo@expo.lcs.mit.edu Discussion of video extensions for X
     

    First ask your site administrator whether you can get these news groups locally. Requests to have the motif mailing list mailed directly to you should be sent to motif-request@alphalpha.com. Requests to have the OPEN LOOK mailing list mailed directly to you should be sent to openlook-request@unify.com. Requests for all the other lists should be sent to mailing-list-name-request@expo.lcs.mit.edu, or uunet!expo.lcs.mit.edu!mailing-list-name-request (for example, to join the ximage mailing list, send mail to ximage-request@expo.lcs.mit.edu).

    The newsgroup comp.window.x (which is the same as xpert), is where users and developers around the world ask and answer questions.

    Training, Consulting, and Support

    Numerous independent vendors provide courses on X programming. Several sources that we are aware of include: Training companies wishing to be listed here should send us information on the courses they offer.

    There are currently no telephone support lines at the X Consortium, because X was developed by a university, not a system manufacturer or software house. Some vendors such as OSF offer support for a fee.

    ICS provides telephone support for a fee. See Section G.3 for their telephone number.

    The X Consortium

    The X Consortium can be reached at:

    MIT X Consortium
    545 Technology Square - Room 217
    Cambridge, MA 02139

    The Consortium's telephone number is (617) 253-8861; its current members are shown below.
     
    Table G-3 : Consortium Members
    Apple Computer, Inc. NCR Corporation
    AT&T UNIX System Laboratories NEC Corporation
    BULL Network Computing Devices, Inc.
    Control Data Corporation Nippon Telegraph and Telephone Corporation
    Convex Computer Corporation Oki Electric Industry Co., Ltd.
    Cray Research, Inc. Olivetti Systems & Networks
    Data General OMRON Corp.
    Digital Equipment Corporation Prime Computer, Inc.
    Du Pont Imaging System The Santa Cruz Operation, Inc.
    Fujitsu America, Inc. Sequent Computer Systems Inc.
    Hewlett-Packard Company Siemens Nixdorf Informationssysteme AG
    Hitachi Silicon Graphics Computer Systems
    Hughes Aircraft Co. Sony Corporation
    IBM Corporation Sun Microsystems, Inc.
    Intergraph Corporation Tandberg Data A/S
    Eastman Kodak Company Tektronix, Inc.
    Kubota Pacific Texas Instruments, Inc.
    Matsushita Electric Industrial CO., LTD. Unisys Corp.
    Mitsubishi Electric Corporation Xerox Corporation
    Motorola, Inc.
     
    Table G-4 : Consortium Affiliates
    Adobe Systems Metheus Corp.
    AGE Logic, Inc. MIPS Computer Systems
    Aptronix, Inc. MITRE Corp.
    ASTEC, Inc. Objectivity, Inc.
    Athenix Corp. Open Software Foundation
    Bitstream, Inc. O'Reilly & Associates, Inc.
    CETIA PCS Computer Systeme GmbH (Germany)
    Chromatics Peritek Corp.
    Codonics, Inc. PsiTech, Inc.
    Industrial Technology Research Institute (China) Quarterdeck Office System
    Data Connection Ltd. Ramtek Corp.
    Evans & Sutherland Samsung Software America
    Frame Technology Corp. ShoGraphics, Inc.
    GIPSI S.A. (France) Snitily Graphics Consulting Services
    GfxBase Solbourne Computer Inc.
    HaL Computer Systems SOUM Corporation (Japan)
    Institute for Information Industry (Taiwan) SPARC International
    Integrated Computer Solutions, Inc. SpectraGraphics Corp.
    Interactive Systems Corp. Stanford University
    Ithaca Software Strategic Research Institute Inc. (Japan)
    IXI Limited Sumitomo Electric Workstation Corp.
    Japan Computer Corporation Tatung Science and Technology
    Jupiter Systems Tyan Computer
    KAIST (Korea Advanced Institute of Science and Technology) Unipalm XTech
    Labtam Australia VisionWare Ltd.
    Liant Software Corporation Visix Software, Inc.
    Locus Computing Corporation Visual Information Technologies, Inc.
    University of Lowell Visual Technology, Inc.
    Megatek Corp. Widget, Inc. (Japan)
    Metro Link, Inc. X/Open Company Ltd.
     

    Most of these companies are preparing products based on X. It should not be long before many different products are available that support X.

    Finding Out for Yourself

    X is unusual in that the source code is freely copyable by anyone as long as the copyright notices are observed. It should be possible for most X programmers to get a copy of the X source code from the sources listed above. Once you understand how the code is organized, you can look up certain details about how X works as long as you have a good knowledge of C and a little persistence. In "Star Wars," the saying was "Use the Force, Luke." In X, it is "Use the Source, Luke."

    Xlib and the server are two distinct chunks of code. Each contains code for sending and receiving information to and from the other over the network using protocol requests, replies, events, and errors. The source tree as supplied on the X distribution tape places the Xlib source in the directory base/lib/X, where base is the top of the entire source tree. Their server source is placed in base/server.

    The procedure for finding out something about an Xlib routine is normally to search for the routine in the Xlib code and then figure out what it does. Sometimes the answer can be found there. Many of the routines, however, simply place their arguments in a protocol request and send it to the server. Then you will have to look in the server code for the answer. To find the correct place in the server code, you will need the symbol for the protocol request, which is the first argument in the GetReq call.

    The server code is much more involved than Xlib itself. The device-dependent portions are in base/server/ddx, and the device-independent portions are in base/server/dix. The device-independent code should be your first stop, because it is here that protocol requests from Xlib arrive and are dispatched to the appropriate code. Search for the protocol request symbol you found in Xlib. It will appear in several source files. Start with the occurrence in dispatch.c, and try to figure out what the code does. This will require following leads to other routines.

    If you do not find a routine in base/server/dix, then it must be in the device-dependent code. base/server/ddx has one directory in it for each brand of hardware to which a sample server has been ported. It also contains the directories /cfb, /mfb, /mi, and /snf, which contain routines used in writing the sample server device-dependent code. Note that servers may include code ostensibly for other machines. For example, the Sun sample server appears to use code in several of the directories for other servers such as dec and hp.

    Xlib and the X protocol are both defined by specification documents, not by any particular implementation. Never depend on the implementation details of the Xlib or server code. If you do, your code may not run on a machine that has optimized X software. This manual documents only those features of Xlib and X in general that are governed by X Consortium standard specifications. If you follow the guidance you find in this volume and the details in Volume Two, Xlib Reference Manual, you will be in good shape.

    Xlib Programming Manual (O'Reilly & Associates, Inc.)