Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 1013

X Window System Protocol, version 11: Alpha update April 1987

Pages: 101
Unclassified
Part 1 of 3 – Pages 1 to 29
None   None   Next

ToP   noToC   RFC1013 - Page 1
Network Working Group                                Robert W. Scheifler
Request for Comments: 1013                                     June 1987



                  X WINDOW SYSTEM PROTOCOL, VERSION 11
                                 Alpha Update
                                  April 1987
     Copyright (c) 1986, 1987 Massachusetts Institute of Technology
                   X Window System is a trademark of M.I.T.


Status of this Memo

   This RFC is distributed to the Internet community for information
   only.  It does not establish an Internet standard.  The X window
   system has been widely reviewed and tested.  The internet community
   is encouraged to experiment with it.  Distribution of this memo is
   unlimited (see copyright notice on page 2).
ToP   noToC   RFC1013 - Page 2
   Permission to use, copy, modify, and distribute this document for any
   purpose and without fee is hereby granted, provided that the above
   copyright notice appear in all copies and that both that copyright
   notice and this permission notice are retained, and that the name of
   M.I.T. not be used in advertising or publicity pertaining to this
   document without specific, written prior permission.  M.I.T. makes no
   representations about the suitability of this document or the
   protocol defined in this document for any purpose.  It is provided
   "as is" without express or implied warranty.

    Author: Robert W. Scheifler
           Laboratory for Computer Science
           545 Technology Square, Room 418
           Cambridge, MA 02139

    Contributors:
           Dave Carver (Digital HPW)
           Branko Gerovac (Digital HPW)
           Jim Gettys (MIT/Project Athena, Digital)
           Phil Karlton (Digital WSL)
           Scott McGregor (Digital SSG)
           Ram Rao (Digital UEG)
           David Rosenthal (Sun)
           Dave Winchell (Digital UEG)

    Implementors of initial server who provided useful input:
           Susan Angebranndt (Digital)
           Raymond Drewry (Digital)
           Todd Newman (Digital)

    Invited reviewers who provided useful input:
           Andrew Cherenson (Berkeley)
           Burns Fisher (Digital)
           Dan Garfinkel (HP)
           Leo Hourvitz (Next)
           Brock Krizan (HP)
           David Laidlaw (Stellar)
           Dave Mellinger (Interleaf)
           Ron Newman (MIT)
           John Ousterhout (Berkeley)
           Andrew Palay (ITC CMU)
           Ralph Swick (MIT)
           Craig Taylor (Sun)
           Jeffery Vroom (Stellar)

   This document does not attempt to provide the rationale or pragmatics
   required to fully understand the protocol or to place it in
   perspective within a  complete system.  Knowledge of X Version 10
   will certainly aid in understanding this document.
ToP   noToC   RFC1013 - Page 3
   The protocol contains many management mechanisms that are not
   intended for normal applications.  Not all mechanisms are needed to
   build a particular user interface.  It is important to keep in mind
   that the protocol is intended to provide mechanism, not policy.

   This document does not attempt to define precise formats or bit
   encodings.

   -------------------------------------------------------------------
ToP   noToC   RFC1013 - Page 4
   SECTION 1.  TERMINOLOGY


   Access control list
           X maintains a list of hosts from which client programs may be
           run.  By default, only programs on the local host may use the
           display, plus any hosts specified in an initial list read by
           the server.  This "access control list" can be changed by
           clients on the local host.  Some server implementations may
           also implement other authorization mechanisms.

   Active grab
           A grab is "active" when the pointer or keyboard is actually
           owned by the single grabbing client.

   Ancestors
           If W is an inferior of A, then A is an "ancestor" of W.

   Atom
           An "atom" is a unique id corresponding to a string name.
           Atoms are used to identify properties, types, and selections.

   Backing store
           When a server maintains the contents of a window, the
           off-screen saved pixels are known as a "backing store".

   Bit gravity
           When a window is resized, the contents of the window are
           not necessarily discarded.  It is possible to request the
           server (though no guarantees are made) to relocate the
           previous contents to some region of the window.  This
           attraction of window contents for some location of a window
           is known as "bit gravity".

   Bitmap
           A "bitmap" is a pixmap of depth one.

   Button grabbing
           Buttons on the pointer may be passively "grabbed" by a
           client.  When the button is pressed, the pointer is then
           actively grabbed by the client.

   Byte order
           For image (pixmap/bitmap) data, byte order is defined by
           the server, and clients with different native byte ordering
            must swap bytes as necessary.  For all other parts of the
           protocol, the byte order is defined by the client, and the
           server swaps bytes as necessary.

   Children
           The "children" of a window are its first-level subwindows.
ToP   noToC   RFC1013 - Page 5
   Client
           An application program connects to the window system server
           by some interprocess communication (IPC) path, such as a TCP
           connection or a shared memory buffer.  This program is the
           window system server.  More precisely, the client is the IPC
           path itself; a program with multiple paths open to the server
           is viewed as multiple clients by the protocol.  Resource
           lifetimes are controlled by connection lifetimes, not by
           program lifetimes.

   Clipping regions
           In a graphics context, a bitmap or list of rectangles can
           be specified to restrict output to a particular region of
           the window.  The image defined by the bitmap or rectangles
           is called a "clipping region".

   Color cell
           An entry in a colormap is known as a "color cell".  An entry
           contains three values specifying red, green and blue
           intensities.  These values are always viewed as 16 bit
           unsigned numbers, with zero being minimum intensity.  The
           values are scaled by the server to match the display
           hardware.  The components of a cell are coincident with
           components of other cells in DirectColor and TrueColor
           colormaps.

   Colormap
           A "colormap" consists of a set of color cells.  A pixel value
           indexes the color map to produce intensities to be displayed.
           Depending on hardware limitations, one or more colormaps may
           be installed at one time, such that windows associated with
           those maps display with true colors.

   Connection
           The IPC path between the server and client program is known
           as a "connection".  A client program typically (but not
           necessarily) has one connection to the server over which
           requests and events are sent.

   Containment
           A window "contains" the pointer if the window is viewable and
           the hotspot of the cursor is within a visible region of the
           window or a visible region of one of its inferiors.  The
           border of the window is included as part of the window for
           containment.  The pointer is "in" a window if the window
           contains the pointer but no inferior contains the pointer.

   Coordinate system
           The coordinate system has X horizontal and Y vertical, with
           the origin [0, 0] at the upper left.  Coordinates are
           discrete, and in terms of pixels.  Each window and pixmap has
ToP   noToC   RFC1013 - Page 6
           its own coordinate system.  For a window, the origin is at
           the inside upper left, inside the border.

   Cursor
           A "cursor" is the visible shape of the pointer on a screen.
           It consist of a hot spot, a source bitmap, a shape bitmap,
           and a pair of colors.  The cursor defined for a window
           controls the visible appearance when the pinter is in that
           window.

   Depth
           The "depth" of a window or pixmap is number of bits per pixel
           it has. The depth of a gcontext is the depth of the root of
           the gcontext.

   Device
           Keyboards, mice, tablets, track-balls, button boxes, etc. are
           all collectively known as input "devices".  The core protocol
           only deals with two devices, "the keyboard" and "the
           pointer".

   Drawable
           Both windows and pixmaps may be used as sources and
           destinations  in graphics operations.  These are collectively
           known as "drawables". However, an InputOnly window cannot be
           used as a source or destination in a graphics operation.

   Event
           Clients are informed of information asynchronously via
           "events". These events may be either asynchronously generated
           from devices, or generated as side effects of client
           requests.  Events are grouped into types; events are never
           sent to a client by the server unless the client has
           specificially asked to be informed of that type of event,
           but other clients can force events to be sent to other
           clients. Events are typically reported relative to a window.

   Event mask
           Events are requested relative to a window.  The set of event
           types a client requests relative to a window described using
           an "event mask".

   Event sychronization
           There are certain race conditions possible when
           demultiplexing device events to clients (in particular
           deciding where pointer and keyboard events should be sent
           when in the middle of window management operations).  The
           event synchronization mechanism allows synchronous processing
           of device events.
ToP   noToC   RFC1013 - Page 7
   Event propagation
           Device-related events "propagate" from the source window to
           ancestor windows until some client has expressed interest in
           handling that type of event, or until the event is discarded
           explicitly.

   Event source
           The smallest window containing the pointer is the "source"
           of a device related event.

   Exposure event
           Servers do not guarantee to preserve the contents of windows
           when windows are obscured or reconfigur contents of regions
           of windows have been lost.

   Extension
           Named "extensions" to the core protocol can be defined to
           extend the system.  Extension to output requests, resources,
           and event types are all possible, and expected.

   Font
           A "font" is an array of glyphs (typically characters).  The
           protocol does no translation or interpretation of character
           sets.  The client simply indicates values used to index the
           glyph array.  A font contains additional metric information
           to determine inter-glyph and inter-line spacing.

   Glyph
           A "glyph" is an image, typically of a character, in a font.

   Grab
           Keyboard keys, the keyboard, pointer buttons, the pointer,
           and the server can be "grabbed" for exclusive use by a
           client.  In general, these facilities are not intended to be
           used by normal applications, but are intended for various
           input and window managers to implement various styles of
           user interfaces.

   Graphics context
           Various information for graphics output is stored in "GC"'s,
           such as foreground pixel, background pixel, line width,
           clipping region, etc.

   Hotspot
           A cursor has an associated "hot spot" which defines a point
           in the cursor that corresponds to the coordinates reported
           for the pointer.

   Identifier
           Each resource has an "identifier", a unique value associated
           with it that clients use to name the resource.  An identifier
ToP   noToC   RFC1013 - Page 8
           can be used over any connection to name the resource.

   Inferiors
           The "inferiors" of a window are all of the subwindows nested
           below it: the children, the children's children, etc.

   Input focus
           The "input focus" is nominally where keyboard input goes.
           Keyboard events are by default sent to the client expressing
           interest on the window the pointer is in.  This is said to be
           a "real estate driven" input focus.  It is also possible to
           attach the keyboard input to a  specific window; events will
           then be sent to the appropriate client independent of the
           pointer position.

   Input manager
           Control over keyboard input is typically provided by an
           "input manager" client.

   InputOnly window
           A window that cannot be used for graphics requests.
           InputOnly windows are "invisible", and can be used to control
           such things as cursors, input event generation, and grabbing.

   InputOutput window
           The "normal" kind of opaque window, used for both input
           and output.

   Key grabbing
           Keys on the keyboard may be passively "grabbed" by a client.
           When the key is pressed, the keyboard is then actively
           grabbed by the client.

   Keyboard grabbing
           A client can actively "grab" control of the keyboard, and key
           events will be sent to that client rather than the client the
           events would normally have been sent to.

   Mapping
           A window is said to be "mapped" if a map call has been
           performed on it.  Unmapped windows are never viewable or
           visible.

   Modifier keys
           Shift, Control, Meta, Super, Hyper, ALT, Compose, Apple,
           CapsLock, ShiftLock, and similar keys are called "modifier"
           keys.

   Obscures
           Window A "obscures" window B if both are viewable
           InputOutput windows and A is higher in the global stacking
ToP   noToC   RFC1013 - Page 9
           order, and the rectangle defined by the outside edges of
           intersects the rectangle defined by the outside edges of B.
           Note the (fine) distinction with "occludes". Also note that
           window borders are included in the calculation.

   Occludes
           Window A "occludes" window B if both are mapped and A is
           higher in the global stacking order, and the rectangle
           defined by the outside edges of A intersects the rectangle
           defined by the outside edges of B.  Note the (fine)
           distinction with "obscures".  Also note that window borders
           are included in the calculation.

   Padding
           Some padding bytes are inserted in the data stream to
           maintain alignment of the protocol requests on natural
           boundaries.  This increases ease of portability to some
           machine architectures.

   Parent window
           If C is a child of P, then P is the "parent" of C.

   Passive grab
           Grabbing a key or button is a "passive" grab.  The grab
           activates when the key or button is actually pressed.

   Pixel value
           A "pixel" is an N-bit value, where N is the number of bit
           planes used in a particular window or pixmap.  For a window,
           a pixel value indexes a colormap to derive an actual color
           to be displayed.

   Pixmap
           A "pixmap" is a three dimensional array of bits.  A pixmap
           is normally thought of as a two dimensional array of pixels,
           where each pixel can be a value from 0 to (2^N)-1, where N
           is the depth (z axis) of the pixmap.  A pixmap can also be
           thought of as a stack of N bitmaps.

   Plane mask
           Graphics operations can be restricted to only affect a
           subset of bit planes of a destination.  A "plane mask" is
           a bit mask describing which planes are to be modified, and
           is stored in a graphics context.

   Pointer
           The "pointer" is the pointing device attached to the cursor,
           and tracked on the screens.

   Pointer grabbing
           A client can actively "grab" control of the pointer, and
ToP   noToC   RFC1013 - Page 10
           button and motion events will be sent to that client rather
           than the client the events would normally have been sent to.

   Pointing device
           A "pointing device" is typically a mouse or tablet, or some
           other device with effective dimensional motion.  There is
           only one visible cursor is defined by the core protocol,
           and it tracks whatever pointing device is attached as the
           pointer.

   Property
           Windows may have associated "properties", consisting of a
           name, a type, a data format, and some data.  The protocol
           places no interpretation on properties, they are intended
           as a general-purpose naming mechanism for clients.  For
           example, clients might share information such as resize
           hints, program names, and icon formats with a window
           manager via properties.

   Property list
           The "property list" of a window is the list of properties
           that have been defined for the window.

   Redirecting control
           Window managers (or client programs) may wish to enforce
            window layout policy in various ways.  When a client
           attempts to change the size or position of a window, the
           operation may be "redirected" to a specified client,
           rather than the operation actually being performed.

   Reply
           Information requested by a client program is sent back to
           the client with a "reply".  Both events and replys are
           multipexed on the same connection.  Most requests do not
           generate replies.

   Request
           A command to the server is called a "request".  It is a
           single block of data sent over a connection.

   Resource
           Windows, pixmaps, cursors, fonts, graphics contexts, and
           colormaps are known as "resources".  They all have unique
           identifiers associated with them for naming purposes.  The
           lifetime of a resource is bounded by the lifetime of the
           connection over which the resource was created.

   Root
           The "root" of a pixmap or gcontext is the same as the root
           of whatever drawable was used when the pixmap or gcontext
           was created.  The "root" of a window is the root window
ToP   noToC   RFC1013 - Page 11
           under which the window was created.

   Root window
           Each screen has a "root window" covering it.  It cannot be
           reconfigured or unmapped, but otherwise acts as a full
           fledged window. A root window has no parent.

   Save set
           The "save set" of a client is a list of other client's
           windows which, if they are inferiors of one of the client's
           windows at connection close, should not be destroyed, and
           which should be remapped if it is unmapped.  Save sets are
           typically used by window managers to avoid lost windows if
           the manager should terminate abnormally.

   Screen
           A server may provide several independent "screens", which
           typically have physically independent monitors.  This would
           be the expected configuration when there is only a single
           keyboard and pointer shared among the screens.

   Server
           The "server" provides the basic windowing mechanism.  It
           handles IPC connections from clients, demultipexes graphics
           requests onto the screens, and multiplexes input back to the
           appropriate clients.

   Server grabbing
           The server can be "grabbed" by a single client for exclusive
           use. This prevents processing of any requests from other
           client connections until the grab is complete.  This is
           typically only a transient state for such things as
           rubber-banding and pop-up menus, or to execute requests
           indivisibly.

   Sibling
           Children of the same parent window are known as "sibling"
           windows.

   Stacking order
           Sibling windows may "stack" on top of each other.  Windows
           above both obscure and occlude lower windows.  This is
           similar to paper on a desk. The relationship between
           sibling windows is known as the "stacking order".

   Stipple
           A "stipple pattern" is a bitmap that is used to tile a
           region to serve as an additional clip mask for a fill
           operation with the foreground color.
ToP   noToC   RFC1013 - Page 12
   Tile
           A pixmap can be replicated in two dimensions to "tile"
           a region.  The pixmap itself is also known as a "tile".

   Timestamp
           A time value, expressed in milliseconds, typically since
           the last server reset.  Timestamp values wrap around (after
           about 49.7 days). The server, given its current time is
           represented by timestamp T, always interprets timestamps
           from clients by treating half of the timestamp space as
           being earlier in time than T, and half of the timestamp
           space as being later in time than T.  One timestamp value
           (named CurrentTime) is never generated by the server;
           this value is reserved for use in requests to represent
           the current server time.

   Type
           A type is an arbitrary atom used to identify the
           interpretation of property data.  Types are completely
           uninterpreted by the server; they are solely for the
           benefit of clients.

   Unviewable
           A window is "unviewable" if it is mapped but some ancestor is
           unmapped.

   Viewable
           A window is "viewable" if it and all of its ancestors are
           mapped.  This does not imply that any portion of the window
           is actually visible.

   Visible
           A region of a window is "visible" if someone looking at the
           screen can actually "see" it:  the window is viewable and the
           region is not occluded by any other window.

   Window gravity
           When windows are resized, subwindows may be repositioned
           automatically relative to some position in the window.  This
           attraction of a subwindow to some part of its parent is known
           as "window gravity".

   Window manager
           Manipulation of windows on the screen, and much of the user
           interface (policy) is typically provided by a "window
           manager" client.

   XYFormat
           The data for a pixmap is said to be in "XYFormat" if it is
           organized as a set of bitmaps representing individual bit
           planes.
ToP   noToC   RFC1013 - Page 13
   ZFormat
           The data for a pixmap is said to be in "ZFormat" if it is
           organized as a set of pixel values in scanline order.

SECTION 2.  PROTOCOL FORMATS


Request Format

   Every request contains an 8-bit "major" opcode, and a 16-bit length
   field expressed in units of 4 bytes.  Every request consists of 4
   bytes of header containing the major opcode, the length field, and a
   data byte) followed by zero or more additional bytes of data; the
   length field defines the total length of the request, including the
   header.  The length field in a request must equal the minimum length
   required to contain the request; if the specified length is smaller
   or larger than the required length, an error is enerated.  Unused
   bytes in a request are not required to be zero.  Major opcodes 128
   through 255 are reserved for extensions.  Extensions are intended
   to contain multiple requests, so extension requests typically have
   an additional minor opcode encoded in the "spare" data byte in the
   request header, but the placement and interpretation of this minor
   opcode, and all other fields in extension requests, are not defined
   by the core protocol. Every request is implicitly assigned a sequence
   number, starting with one,used in replies, errors, and events.

Reply Format

   Every reply contains a 32-bit length field expressed in units of 4
   bytes. Every reply consists of 32 bytes, followed by zero or more
   additional bytes of data, as specified in the length field.  Unused
   bytes within a reply are not guaranteed to be zero.  Every reply
   also contains the least significant 16 bits of the sequence number
   of the corresponding request.

Error Format

   Error reports are 32 bytes long.  Every error includes an 8-bit error
   code. Error codes 128 through 255 are reserved for extensions.  Every
   error also includes the major and minor opcodes of the failed
   request, and the least significant 16 bits of the sequence number of
   the request.  For the following errors (see Section 5), the failing
   resource id is also returned: Colormap, Cursor, Drawable, Font,
   GContext, IDChoice, Pixmap, and Window.  For Atom errors, the failing
   atom is returned.  For Value errors, the failing value is returned.
   Other core errors return no additional data.  Unused bytes within
   an error are not guaranteed to be zero.

Event Format

   Events are 32 bytes long.  Unused bytes within an event are not
ToP   noToC   RFC1013 - Page 14
   guaranteed to be zero.  Every event contains an 8-bit type code.  The
   most significant bit in this code is set if the event was generated
   from a SendEvent request. Event codes 64 through 127 are reserved for
   extensions, although the core protocol does not define a mechanism
   for selecting interest in such events. Every core event (with the
   exception of KeymapNotify) also contains the least significant 16
   bits of the sequence number of the last request issued by the client
   that was (or is currently being) processed by the server.


SECTION 3.  SYNTAX


   The syntax {...} encloses a set of alternatives.

   The syntax [...] encloses a set of structure components.

   In general, TYPEs are in upper case and AlternativeValues are
   capitalized.

   Requests in Section 10 are described in the following format:

       RequestName
               arg1: type1
               ...
               argN: typeN
           =>
               result1: type1
               ...
               resultM: typeM

               Errors: kind1, ..., kindK

               Description.

If no => is present in the description, then the request has no
reply (it is asynchronous), although errors may still be reported.

Events in Section 12 are described in the following format:

    EventName
            value1: type1
            ...
            valueN: typeN

            Description.
ToP   noToC   RFC1013 - Page 15
SECTION 4.  COMMON TYPES


LISTofFOO

   A type name of the form LISTofFOO means a counted list of elements
   of type FOO; the size of the length field may vary (it is not
   necessarily the same size as a FOO), in some cases may be implicit,
   and is not fully specified in this document.

BITMASK and LISTofVALUE

   The types BITMASK and LISTofVALUE are somewhat special.  Various
   requests contain arguments of the form:
           value-mask: BITMASK
           value-list: LISTofVALUE
   used to allow the client to specify a subset of a heterogeneous
   collection of "optional" arguments.  The value-mask specifies which
   arguments are to be provided; each such argument is assigned a unique
   bit position.  The representation of the BITMASK will typically
   contain more bits than there are defined arguments; unused bits in
   the value-mask must be zero (or the server generates a Value error).
   The value-list contains one value for each one bit in the mask, from
   least to most significant bit in the mask.  Each value is represented
   with 4 bytes, but the actual value occupies only the least
   significant bytes as required; the values of the unused bytes do not
   matter.

Or Types

   A type of the form "T1 or ... or Tn" means the union of the indicated
   types; a single-element type is given as the element without
   enclosing braces.

DEVICE: 32-bit id (<class,model,manufacturer,unit> 8 bits each)
WINDOW: 32-bit id
PIXMAP: 32-bit id
CURSOR: 32-bit id
FONT: 32-bit id
GCONTEXT: 32-bit id
COLORMAP: 32-bit id
DRAWABLE: WINDOW or PIXMAP
ATOM: 32-bit id (top 3 bits guaranteed to be zero)
VISUALID: 32-bit id (top 3 bits guaranteed to be zero)
VALUE: 32-bit quantity (used only in LISTofVALUE)
INT8: 8-bit signed integer
INT16: 16-bit signed integer
INT32: 32-bit signed integer
CARD8: 8-bit unsigned integer
CARD16: 16-bit unsigned integer
CARD32: 32-bit unsigned integer
ToP   noToC   RFC1013 - Page 16
TIMESTAMP: CARD32
BITGRAVITY: {Forget, Static,
             NorthWest, North, NorthEast,
             West, Center, East,
             SouthWest, South, SouthEast}
WINGRAVITY: {Unmap, Static,
             NorthWest, North, NorthEast,
             West, Center, East,
             SouthWest, South, SouthEast}
BOOL: {True, False}
EVENT: {KeyPress, KeyRelease,
        OwnerGrabButton,
        ButtonPress, ButtonRelease, EnterWindow, LeaveWindow,
        PointerMotion, PointerMotionHint,
        Button1Motion, Button2Motion, Button3Motion,
        Button4Motion, Button5Motion, ButtonMotion
        Exposure, VisibilityChange,
        StructureNotify, ResizeRedirect,
        SubstructureNotify, SubstructureRedirect,
        FocusChange,
        PropertyChange, ColormapChange,
        KeymapState}
POINTEREVENT: {ButtonPress, ButtonRelease, EnterWindow, LeaveWindow,
               PointerMotion, PointerMotionHint,
               Button1Motion, Button2Motion, Button3Motion,
               Button4Motion, Button5Motion, ButtonMotion
               KeymapState}
DEVICEEVENT: {KeyPress, KeyRelease,
              ButtonPress, ButtonRelease,
              PointerMotion,
              Button1Motion, Button2Motion, Button3Motion,
              Button4Motion, Button5Motion, ButtonMotion}
KEYCODE: CARD8
BUTTON: CARD8
KEYMASK: {Shift, CapsLock, Control, Mod1, Mod2, Mod3, Mod4, Mod5}
BUTMASK: {Button1, Button2, Button3, Button4, Button5}
KEYBUTMASK: KEYMASK or BUTMASK
STRING8: LISTofCARD8
STRING16: LISTofCHAR2B
CHAR2B: [byte1, byte2: CARD8]
POINT: [x, y: INT16]
RECTANGLE: [x, y: INT16,
            width, height: CARD16]
ARC: [x, y: INT16,
      width, height: CARD16,
      angle1, angle2: INT16]
HOST: [family: {Internet, NS, ECMA, Datakit, DECnet}
       address: LISTofCARD8]

   The [x,y] coordinates of a RECTANGLE specify the upper left corner.
ToP   noToC   RFC1013 - Page 17
   The primary interpretation of "large" characters in a STRING16 is
   that they are composed of two bytes used to index a 2-D matrix;
   hence the use of CHAR2B rather than CARD16.  This corresponds to
   the JIS/ISO method of indexing two-byte characters.  It is expected
   that most "large" fonts will be defined with two-byte matrix
   indexing.  For large fonts constructed with linear indexing, a
   CHAR2B can be interpreted as a 16-bit number by treating byte1 as
   the most significant byte; this means that clients should always
   transmit such 16-bit character values most significant byte first,
   as the server will never byte-swap CHAR2B quantities.

   The length, format, and interpretation of a HOST address are specific
   to the family.


SECTION 5.  ERRORS

   In general, when a request terminates with an error, the request has
   no side effects (i.e., there is no partial execution).  The only
   requests for which this is not true are ChangeWindowAttributes,
   ChangeGC, PolyText8, PolyText16, FreeColors, StoreColors, and
   ChangeKeyboardControl.

   The following error codes can be returned by the various requests:

Access
           An attempt to grab a key/button combination already grabbed
           by another client.

           An attempt to free a colormap entry not allocated by the
           client.

           An attempt to store into a read-only or an unallocated
           colormap entry.

           An attempt to modify the access control list from other than
           the local (or otherwise authorized) host.

           An attempt to select an event type, that at most one client
           can select at a time, when another client has already
           selected it.

Alloc
           The server failed to allocate the requested resource.

           Note that this only covers allocation errors at a very coarse
           level, and is not intended to (nor can it in practice hope
           to) cover all cases of a server running out of allocation
           space in the middle of service.
ToP   noToC   RFC1013 - Page 18
           The semantics when a server runs out of allocation space are
           left unspecified.

Atom
           A value for an ATOM argument does not name a defined ATOM.

Colormap
           A value for a COLORMAP argument does not name a defined
           COLORMAP.

Cursor
           A value for a CURSOR argument does not name a defined CURSOR.

Drawable
           A value for a DRAWABLE argument does not name a defined
           WINDOW or PIXMAP.

Font
           A value for a FONT or <FONT or GCONTEXT> argument does not
           name a defined FONT.

GContext
           A value for a GCONTEXT argument does not name a defined
           GCONTEXT.

IDChoice
           The value chosen for a resource identifier is either not
           included in the range assigned to the client, or is already
           in use.

Implementation
           The server does not implement some aspect of the request.  A
           server which generates this error for a core request is
           deficient.  As such, this error is not listed for any of the
           requests, but clients should be prepared to receive such
           errors, and handle or discard them.

Length
           The length of a request is shorter or longer than that
           required to minimally contain the arguments.

Match
           An InputOnly window is used as a DRAWABLE.

           Some argument (or pair of arguments) has the correct type and
           range, but fails to "match" in some other way required by the
           request.

Name
           A font or color of the specified name does not exist.
ToP   noToC   RFC1013 - Page 19
Pixmap
           A value for a PIXMAP argument does not name a defined PIXMAP.

Property
           The requested property does not exist for the specified
           window.

Request
           The major or minor opcode does not specify a valid request.

Value
           Some numeric value falls outside the range of values accepted
           by the request.  Unless a specific range is specified for an
           argument, the full range defined by the argument's type is
           accepted.  Any argument defined as a set of alternatives can
           generate this error.

Window
           A value for a WINDOW argument does not name a defined WINDOW.


Note:  the Atom, Colormap, Cursor, Drawable, Font, GContext, Pixmap,
and Window errors are also used when the argument type is extended
by union with a set of fixed alternatives, e.g.,<Window or
PointerRoot or None>.

SECTION 6.  KEYBOARDS

   Keycodes are always in the inclusive range [8,255].

   For keyboards with both left-side and right-side modifier keys (e.g.,
   Shift and Control), the mask bits in the protocol always define the
   OR of the keys. If electronically distinguishable, they can have
   separate up/down events generated, and clients that want to
   distinguish can track the individual states manually.

   <As part of the core we need to define a universal association
   between keycaps and keycodes.  A keycap is the graphical information
   imprinted on a keyboard key, e.g., "$ 4", "T", "+ =".>


SECTION 7.  POINTERS

   Buttons are always numbered starting with one.


SECTION 8.  PREDEFINED ATOMS

   Predefined atoms are not strictly necessary, and may not be useful in
   all environments, but will eliminate many InternAtom requests in most
   applications.  The core protocol imposes no semantics on these names,
ToP   noToC   RFC1013 - Page 20
   except as they are used in FONTPROP structures (see QueryFont).  Note
   that upper/lower case matters.

      BITMAP               ICON_SIZE               RGB_GREEN_MAP
      COMMAND              ITALIC_ANGLE            RGB_RED_MAP
      COPYRIGHT            MAX_SPACE               SECONDARY
      CUT_BUFFER0          MIN_SPACE               SIZE_HINTS
      CUT_BUFFER1          NAME                    STRIKEOUT_ASCENT
      CUT_BUFFER2          NORMAL_HINTS            STRIKEOUT_DESCENT
      CUT_BUFFER3          NORM_SPACE              STRING
      CUT_BUFFER4          PIXMAP                  SUBSCRIPT_X
      CUT_BUFFER5          POINT_SIZE              SUBSCRIPT_Y
      CUT_BUFFER6          PRIMARY                 SUPERSCRIPT_X
      CUT_BUFFER7          QUAD_WIDTH              SUPERSCRIPT_Y
      DEFAULT_CHAR         RECTANGLE               UNDERLINE_POSITION
      END_SPACE            RESIZE_HINT             UNDERLINE_THICKNESS
      FACE_NAME            RESOLUTION              WEIGHT
      FAMILY_NAME          RGB_BEST_MAP            WINDOW
      FONT_ASCENT          RGB_BLUE_MAP            WM_HINTS
      FONT_DESCENT         RGB_COLOR_MAP           X_HEIGHT
      ICON                 RGB_DEFAULT_MAP         ZOOM_HINTS
      ICON_NAME


SECTION 9.  CONNECTION SETUP

   For remote clients, the X protocol can be built on top of any
   reliable byte stream.  For TCP connections, displays on a given host
   a numbered starting from 0, and the server for display N listens and
   accepts connections on port 6000+N.

   The client must send an initial byte of data to identify the byte
   order to be employed.  The value of the byte must be octal 102 or
   154.  The value 102 (ASCII uppercase B) means values are transmitted
   most significant byte first, and value 154 (ASCII lowercase l) means
   values are transmitted least significant byte first.  Except where
   explicitly noted in the protocol, all 16-bit and 32-bit quantities
   sent by the client must be transmitted with this byte order, and all
   16-bit and 32-bit quantities returned by the server will be
   transmitted with this byte order.

   Following the byte-order byte, the following information is sent by
   the client at connection setup:

           protocol-major-version: CARD16
           protocol-minor-version: CARD16
           authorization-protocol-name: STRING8
           authorization-protocol-data: STRING8

           The version numbers indicate what version of the protocol the
           client expects the server to implement.  See below for an
ToP   noToC   RFC1013 - Page 21
           explanation. The authorization name indicates what
           authorization protocol the client expects the server to use,
           and the data is specific to that protocol. Specification of
           valid authorization mechanisms is not part of the core X
           protocol.  It is hoped that eventually one authorization
           protocol will be agreed upon.  In the mean time, a server
           that implements a different protocol than the client expects,
           or a server that only implements the host-based mechanism,
           will simply ignore this information.

   Received by the client at connection setup:
           success: BOOL
           protocol-major-version: CARD16
           protocol-minor-version: CARD16
           length: CARD16

           Length is the amount of additional data to follow, in units
           of 4 bytes. The version numbers are an escape hatch in case
           future revisions of the protocol are necessary.  In general,
           the major version would increment for incompatible changes,
           and the minor version would increment for small upward
           compatible changes.  Barring changes, the major version
           will be eleven, and the minor version will be zero.  The
           protocol version numbers returned indicate the protocol the
           server actually supports.  This might not equal the version
           sent by the client.  The server can (but need not) refuse
           connections from clients that offer a different version
           than the server supports.  A server can (but need not)
           support more than one version simultaneously.

   Additional data received if authorization fails:
           reason: STRING8

   Additional data received if authorization is accepted:
           vendor: STRING8
           release-number: CARD32
           resource-id-base, resource-id-mask: CARD32
           image-byte-order: {LSBFirst, MSBFirst}
           bitmap-format-scanline-unit: {8, 16, 32}
           bitmap-format-scanline-pad: {8, 16, 32}
           bitmap-format-bit-order: {LeastSignificant, MostSignificant}
           pixmap-formats: LISTofFORMAT
           roots: LISTofSCREEN
           keyboard: DEVICE
           pointer: DEVICE
           motion-buffer-size: CARD32
           maximum-request-length: CARD16

           where

             FORMAT: [depth: CARD8,
ToP   noToC   RFC1013 - Page 22
                      bits-per-pixel: {4, 8, 16, 24, 32}
                      scanline-pad: {8, 16, 32}]
             SCREEN: [root: WINDOW
                      device: DEVICE
                      width-in-pixels, height-in-pixels: CARD16
                      width-in-millimeters,height-in-millimeters:CARD16
                      allowed-depths: LISTofDEPTH
                      root-depth: CARD8
                      root-visual: VISUALID
                      default-colormap: COLORMAP
                      white-pixel, black-pixel: CARD32
                      min-installed-maps, max-installed-maps: CARD16
                      backing-stores: {Never, WhenMapped, Always}
                      save-unders: BOOL
                      current-input-masks: SETofEVENT]
            DEPTH: [depth: CARD8
                      visuals: LISTofVISUALTYPE]
            VISUALTYPE: [visual-id: VISUALID
                         class: {StaticGray, StaticColor,
                                 TrueColor,GrayScale, PseudoColor,
                                 DirectColor}
                                 red-mask, green-mask, blue-mask: CARD32
                                 bits-per-rgb-value: CARD8
                                 colormap-entries: CARD16]

   Per server information:

   The vendor string gives some indentification of the owner of the
   server implementation.  The semantics of the release-number is
   controlled by the vendor.

   The resource-id-mask contains a single contiguous set of bits (at
   least 18); the client allocates resource ids by choosing a value
   with (only) some subset of these bits set, and ORing it with
   resource-id-base.  Only values constructed in this way can be
   used to name newly created resources over this connection.
   Resource ids never have the top 3 bits set.  The client is not
   restricted to linear or contiguous allocation of resource ids.
   Once an id has been freed, it can be reused, but this should not
   be necessary. An id must be unique with respect to the ids of
   all other resources, not just other resources of the same type.

   Although the server is in general responsible for byte swapping
   data to match the client, images are always transmitted and
   received in formats (including byte order) specified by the
   server.  The byte order for images is given by image-byte-order,
   and applies to each scanline unit in XYFormat (bitmap) format,
   and to each pixel value in ZFormat.

   A bitmap is represented in scanline order.  Each scanline is padded
   to a multiple of bits as given by bitmap-format-scanline-pad.  The
ToP   noToC   RFC1013 - Page 23
   pad bits are of arbitrary value.  The scanline is quantized in
   multiples of bits as given by bitmap-format-scanline-unit.  Within
   each unit, the leftmost bit in the bitmap is either the least or
   most significant bit in the unit, as given by
   bitmap-format-bit-order.  If a pixmap is represented in XYFormat,
   each plane is represented as a bitmap, and the planes appear from
   most to least significant in bit order.

   For each pixmap depth supported by some screen, pixmap-formats lists
   the ZFormat used to represent images of that depth.  In ZFormat, the
   pixels are in scanline order, left to right within a scanline.  The
   number of bits used to hold each pixel is given by bits-per-pixel,
   and may be larger than strictly required by the depth.  When the
   bits-per-pixel is 4, the order of nibbles in the byte is the same as
   the image byte-order.  Each scanline is padded to a multiple of bits
   as given by scanline-pad.

   How a pointing device roams the screens is up to the server
   implementation, and is transparent to the protocol.  No geometry
   among screens is defined.

   The server may retain the recent history of pointer motion, and to a
   finer granularity than is reported by MotionNotify events.  Such
   history is available via the GetPointerMotions request.  The
   approximate size of the history buffer is given by
   motion-buffer-size.

   Maximum-request-length specifies the maximum length of a request, in
   4-byte units, accepted by the server; i.e., this is the maximum value
   that can appear in the length field of a request.  Requests larger
   than this generate a Length error, and the server will read and
   simply discard the entire request.  Maximum-request-length will
   always be at least 4096 (i.e., requests of length up to and including
   16384 bytes will be accepted by all servers).

   Per screen information:

   The allowed-depths specifies what pixmap and window depths are
   supported.  Pixmaps are supported for each depth listed, and windows
   of that depth are supported if at least one visual type is listed for
   the depth.  A pixmap depth of one is always supported and listed, but
   windows of depth one might not be supported.  A depth of zero is
   never listed, but zero-depth InputOnly windows are always supported.

   Root-depth and root-visual specify the depth and visual type of the
   root window.  Width-in-pixels and height-in-pixels specify the size
   of the root window (which cannot be changed).  The class of the root
   window is always InputOutput.  Width-in-millimeters and
   height-in-millimeters can be used to determine the physical size and
   the aspect ratio.
ToP   noToC   RFC1013 - Page 24
   The default-colormap is the one initially associated with the root
   window.  Clients with minimal color requirements creating windows of
   the same depth as the root may want to allocate from this map by
   default.

   Black-pixel and white-pixel can be used in implementing a
   "monochrome" application.  These pixel values are for permanently
   allocated entries in the default-colormap; the actual RGB values may
   be settable on some screens.

   The border of the root window is initially a pixmap filled with the
   black-pixel.  The initial background of the root window is a pixmap
   filled with some unspecified two-color pattern using black-pixel and
   white-pixel.

   Min-installed-maps specifies the number of maps that can be
   guaranteed to installed simultaneously (with InstallColormap),
   regardless of the number of entries allocated in each map.
   Max-installed-maps specifies the maximum number of maps that might
   possibly be installed simultaneously, depending on their
   allocations. For the typical case of a single hardware colormap,
   both values will be one.

   Backing-stores indicates when the server supports backing stores for
   this screen, although it may be storage limited in the number of
   windows it can support at once.  If save-unders is True, then the a
   server can support the save-under mode in CreateWindow and
   ChangeWindowAttributes, although again it may be storage limited.

   The current-input-events is what GetWindowAttributes would return for
   the all-event-masks for the root window.

   Per visual-type information:

   A given visual type might be listed for more than one depth, or for
   more than one screen.

   For PseudoColor, a pixel value indexes a colormap to produce
   independent RGB values; the RGB values can be changed dynamically.
   GrayScale is treated the same as PseudoColor, except which primary
   drives the screen is undefined, so the client should always store
   the same value for red, green, and blue in colormaps.  For
   DirectColor, a pixel value is decomposed into separate RGB
   subfields, and each subfield separately indexes the colormap for
   the corresponding value; The RGB values can be changed dynamically.
   TrueColor is treated the same as DirectColor, except the colormap
   has predefined read-only RGB values, which are server-dependent,
   but provide (near-)linear ramps in each primary.  StaticColor is
   treated the same as PseudoColor, except the colormap has
   predefined read-only RGB values, which are server-dependent.
   StaticGray is treated the same as StaticColor, except the red,
ToP   noToC   RFC1013 - Page 25
   green, and blue values are equal for any single pixel value,
   resulting in shades of gray.  StaticGray with a two-entry colormap
   can be thought of as "monochrome".

   The red-mask, green-mask, and blue-mask are only defined for
   DirectColor and TrueColor; each has one contiguous set of bits, with
   no intersections.

   The bits-per-rgb-value specifies the log base 2 of the approximate
   number of distinct color values (individually) of red, green, and
   blue. Actual RGB values are always passed in the protocol within a
   16-bit spectrum.

   The colormap-entries defines the number of available colormap entries
   in a newly created colormap.  For DirectColor and TrueColor, this
   will usually be the size of an individual pixel subfield.

SECTION 10.  REQUESTS


CreateWindow
           wid, parent: WINDOW
           class: {InputOutput, InputOnly, CopyFromParent}
           depth: CARD8
           visual: VISUALID or CopyFromParent
           x, y: INT16
           width, height, border-width: CARD16
           value-mask: BITMASK
           value-list: LISTofVALUE

           Errors: IDChoice, Window, Pixmap, Colormap, Cursor, Match,
           Value, Alloc

           Creates an unmapped window, and assigns the identifier wid
           to it.

           A class of CopyFromParent means the class is taken from the
           parent.  A depth of zero for class InputOutput or
           CopyFromParent means the depth is taken from the parent.
           A visual of CopyFromParent means the visual type is taken
           from the parent.  For class InputOutput, the visual type
           and depth must be a combination supported for the screen
           (else a Match error); the depth need not be the same as the
           parent, but the parent must not be of class InputOnly (else
           a Match error).  For class InputOnly, the depth must be
           zero (else a Match error), and the visual must be one
           supported for the screen (else a Match error), but the
           parent may have any depth and class.

           The server essentially acts as if InputOnly windows do not
           exist for the purposes of graphics requests, exposure
ToP   noToC   RFC1013 - Page 26
           processing, and VisibilityNotify events.  An InputOnly window
           cannot be used as a drawable (as a source or destination for
           graphics requests).  InputOnly and InputOutput windows act
           identically in other respects (properties, grabs, input
           control, and so on).

           The window is placed on top in the stacking order with
           respect to siblings.  The x and y coordinates are relative
           to the parent's origin, and specify the position of the upper
           left outer corner of the window (not the origin).  The width
           and height specify the inside size, not including the border,
           and must be non-zero.  The border-width for an InputOnly
           window must be zero (else a Match error).

           The value-mask and value-list specify attributes of the
           window that are to be explicitly initialized.  The possible
           values are:

               background-pixmap: PIXMAP or None or ParentRelative
               background-pixel: CARD32
               border-pixmap: PIXMAP or CopyFromParent
               border-pixel: CARD32
               bit-gravity: BITGRAVITY
               win-gravity: WINGRAVITY
               backing-store: {NotUseful, WhenMapped, Always}
               backing-bit-planes: CARD32
               backing-pixel: CARD32
               save-under: BOOL
               event-mask: SETofEVENT
               do-not-propagate-mask: SETofDEVICEEVENT
               override-redirect: BOOL
               colormap: COLORMAP or CopyFromParent
               cursor: CURSOR or None

           The default values, when attributes are not explicitly
           initialized, are:

               background-pixmap: None
               border-pixmap: CopyFromParent
               bit-gravity: Forget
               win-gravity: NorthWest
               backing-store: NotUseful
               backing-bit-planes: all ones
               backing-pixel: zero
               save-under: False
               event-mask: {} (empty set)
               do-not-propagate-mask: {} (empty set)
               override-redirect: False
               colormap: CopyFromParent
               cursor: None
ToP   noToC   RFC1013 - Page 27
           Only the following attributes are defined for InputOnly
           windows: win-gravity, event-mask, do-not-propagate-mask,
           and cursor.  It is a Match error to specify any other
           attributes for InputOnly windows.

           If background-pixmap is given, it overrides the default
           background-pixel.  The background pixmap and the window must
           have the same root and the same depth (else a Match error).
           Any size pixmap can be used, although some sizes may be
           faster than others.  If background None is specifed, the
           window has no defined background.  If background
           ParentRelative is specified, the parent's background is
           used, but the window must have the same depth as the parent
           (else a Match error); if the parent has background None,
           then the window will also have background None.  A copy
           of the parent's background is not made; the parent's
           background is reexamined each time the window background is
           required.  If background-pixel is given, it overrides the
           default and any background-pixmap given, and a pixmap of
           undefined size filled with background-pixel is used for the
           background.  For a  ParentRelative background, the
           background tile origin always aligns with the parent's
           background tile origin; otherwise the background tile
           origin is always the window origin.

           When regions of the window are exposed and the server has
           not retained the contents, the server automatically tiles
           the regions with the window's background unless the window
           has a background of None, in which case the previous screen
           contents are simply left in place. Exposure events are then
           generated for the regions, even if the  background is None.

           The border tile origin is always the same as the background
           tile origin.  If border-pixmap is given, it overrides the
           default border-pixel.  The border pixmap and the window must
           have the same root and the same depth (else a Match error).
           Any size pixmap can be used, although some sizes may faster
           than others.  If CopyFromParent is given, the parent's border
           pixmap is copied (subsequent changes to the parent do not
           affect the child), but the window must have the same depth
           as the parent (else a Match error).  If border-pixel is
           given, it overrides the default and any border-pixmap given,
           and a pixmap of undefined size filled with border-pixel is
           used for the border.

           Output to a window is always clipped to the inside of the
           window, so that the border is never affected.

           The bit-gravity defines which region of the window should be
           retained if the window is resized, and win-gravity defines
           how the window should be repositioned if the parent is
ToP   noToC   RFC1013 - Page 28
           resized; see ConfigureWindow.

           A backing-store of WhenMapped advises the server that
           maintaining contents of obscured regions when the window
           is mapped would be beneficial.  A backing-store of Always
           advises the server that maintaining contents even when the
           window is unmapped would be beneficial.  Note that, even if
           the window is larger than its parent, the server should
           maintain complete contents, not just the region within the
           parent boundaries.  If the server maintains contents,
           Exposure events will not be generated, but the server may
           stop maintaining contents at any time.  A value of NotUseful
           advises the server that maintaining contents is unnecessary,
           although a server may still choose to maintain contents.

           Backing-bit-planes indicates (with one bits) which bit
           planes of the window hold dynamic data that must be preserved
           in backing-stores. Backing-pixel specifies what value to use
           in planes not covered by backing-bit-planes.  The server is
           free to only save the specified bit planes in the
           backing-store, and regenerate the remaining planes with the
           specified pixel value.

           If save-under is True, the server is advised that, when
           this window is mapped, saving the contents of windows it
           obscures would be beneficial.

           The event-mask defines which events the client is interested
           in for this window (or, for some event types, inferiors of
           the window).  The do-not-propagate-mask defines which events
           should not be propagated to ancestor windows when no client
           has the event type selected in this window.

           Override-redirect specifies whether map and configure
           request on this window should override a SubstructureRedirect
           on the parent, typically to inform a window manager not to
           tamper with the window.

           The colormap specifies the colormap, that best reflects the
           "true" colors of the window.  Servers capable of supporting
           hardware colormaps may use this information, and window
           managers may use it for InstallColormap requests.  The
           colormap must have the same visual type as the window
           (else a match error). If CopyFromParent is specified, the
           parents's colormap is copied (subsequent changes to the
           parent do not affect the child), but the window must have
           the same visual type as the parent (else a Match error) an
           the parent must not have a colormap of None (else a Match
           error).
ToP   noToC   RFC1013 - Page 29
           If a cursor is specified, it will be used whenever the
           pointer is in the window.  If None is specified, the
           parent's cursor will be used when the pointer is in the
           window, and any change in the parent's cursor will
           cause an immediate change in the display cursor.

           This request generates a CreateNotify event.

           The background and border pixmaps and the cursor may be
           freed immediately if no further explicit references to
           them are to be made.

           Subsequent drawing into the background or border pixmap has
           an undefined effect on the window state; the server might or
           might not make a copy of the pixmap.

ChangeWindowAttributes
          window: WINDOW
          value-mask: BITMASK
          value-list: LISTofVALUE

          Errors: Window, Pixmap, Colormap, Cursor, Match, Value,
                  Access

          The value-mask and value-list specify which attributes are
          to be changed.  The values and restrictions are the same
          as for CreateWindow.

          Changing the background does not cause the window contents
          to be changed.  Setting the border, or changing the
          background such that border tile origin changes, causes the
          border to be repainted. Changing the background of a root
          window to None or ParentRelative restores the default
          background pixmap. Changing the border of a root window to
          CopyFromParent restores the default border pixmap.

           Changing the back-store of an obsecured window to
           WhenMapped or Always, or changing the backing-bit-planes,
           backing-pixel, or save-under of a mapped window, may have
           no immediate effect.

           Multiple clients can select input on the same window; their
           event-masks are disjoint.  When an event is generated it
           will be reported to all interested clients.  However, at
           most one client at a time can select for
           SubstructureRedirect, at most one client at a time can
           select for ResizeRedirectr, and at most one client at a
           time can select for ButtonPress.

           There is only one do-not-propagate-mask for a window, not
           one per client.


(next page on part 2)

Next Section