diff options
Diffstat (limited to 'doc/xorg-docs/man')
| -rw-r--r-- | doc/xorg-docs/man/Makefile.am | 23 | ||||
| -rw-r--r-- | doc/xorg-docs/man/general/Consortium.man | 238 | ||||
| -rw-r--r-- | doc/xorg-docs/man/general/Makefile.am | 57 | ||||
| -rw-r--r-- | doc/xorg-docs/man/general/Standards.man | 435 | ||||
| -rw-r--r-- | doc/xorg-docs/man/general/X.man | 1334 | ||||
| -rw-r--r-- | doc/xorg-docs/man/general/XOrgFoundation.man | 56 | ||||
| -rw-r--r-- | doc/xorg-docs/man/general/XProjectTeam.man | 91 | ||||
| -rw-r--r-- | doc/xorg-docs/man/general/Xprint.man | 421 | ||||
| -rw-r--r-- | doc/xorg-docs/man/general/Xprint.sgml | 627 | ||||
| -rw-r--r-- | doc/xorg-docs/man/general/security.man | 290 |
10 files changed, 3572 insertions, 0 deletions
diff --git a/doc/xorg-docs/man/Makefile.am b/doc/xorg-docs/man/Makefile.am new file mode 100644 index 000000000..68eda4914 --- /dev/null +++ b/doc/xorg-docs/man/Makefile.am @@ -0,0 +1,23 @@ +# Copyright 2005 Red Hat, Inc. +# +# Permission to use, copy, modify, distribute, and sell this software +# and its documentation for any purpose is hereby granted without fee, +# provided that the above copyright notice appear in all copies and +# that both that copyright notice and this permission notice appear in +# supporting documentation, and that the name of Red Hat not be used in +# advertising or publicity pertaining to distribution of the software +# without specific, written prior permission. Red Hat makes no +# representations about the suitability of this software for any +# purpose. It is provided "as is" without express or implied warranty. +# +# RED HAT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, +# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN +# NO EVENT SHALL RED HAT BE LIABLE FOR ANY SPECIAL, INDIRECT OR +# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS +# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE +# USE OR PERFORMANCE OF THIS SOFTWARE. +# +# Process this file with autoconf to create configure. + +SUBDIRS = general diff --git a/doc/xorg-docs/man/general/Consortium.man b/doc/xorg-docs/man/general/Consortium.man new file mode 100644 index 000000000..b7080199c --- /dev/null +++ b/doc/xorg-docs/man/general/Consortium.man @@ -0,0 +1,238 @@ +.\" $TOG: Consortium.cpp /main/71 1997/10/13 14:55:16 kaleb $ +.\" Copyright (c) 1993, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the "Software"), +.\" to deal in the Software without restriction, including without limitation +.\" the rights to use, copy, modify, merge, publish, distribute, sublicense, +.\" and/or sell copies of the Software, and to permit persons to whom the +.\" Software furnished to do so, subject to the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included in +.\" all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +.\" THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +.\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF +.\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +.\" SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall not +.\" be used in advertising or otherwise to promote the sale, use or other +.\" dealing in this Software without prior written authorization from the +.\" X Consortium. +.\" +.\" $XFree86$ +.\" +.TH XCONSORTIUM __miscmansuffix__ __xorgversion__ +.SH NAME +XConsortium \- X Consortium information +.SH SYNOPSIS +Release 6.3 of X Version 11 was brought to you by X Consortium, Inc. +.SH DESCRIPTION +The X Consortium was an independent, not-for-profit Delaware membership +corporation. It was formed in 1993 as the successor to the MIT X Consortium. +The purpose of the X Consortium was to foster the development, evolution, and +maintenance of the X Window System, a comprehensive set of vendor-neutral, +system-architecture neutral, network-transparent windowing and user interface +standards. +.PP +The X Window System was created in the mid-1980s at the Massachusetts +Institute of Technology. In 1988, MIT formed a member-funded consortium to +provide the technical and administrative leadership necessary to support +further development of the X Window System. In 1992, MIT and the membership +decided it was in their best interests to move the consortium out of MIT and +create an independent, stand-alone organization. All rights to the +X Window System were assigned by MIT to X Consortium, Inc. on January 1, 1994. +X Consortium, Inc. closed its doors on December 31, 1996. All rights to the +X Window System have been assigned to the Open Software Foundation. +.PP +The X Consortium was financially self-supporting through membership fees. +There are no license fees associated with the use of X Window System standards +and code developed by the X Consortium. Membership in the X Consortium was +open to any organization willing to execute a membership agreement. +.PP +The X Consortium was a highly participative body. Members were encouraged to +actively cooperate with the staff and other members in the design and review +of proposed specifications, and in the design, coding and testing of sample +implementations of those specifications. +.PP +The X Consortium accomplished most of its work using electronic mail over the +Internet, with individual mailing lists for working groups. Internet +electronic mail connectivity was viewed as a requirement for useful +participation in X Consortium activities. Meetings were held as necessary, +often in conjunction with industry conferences and trade shows. +.SH STAFF +.nf +President: +Bob Scheifler + +Office Manager: +Janet O'Halloran + +Director of Marketing: +Paul Lavallee + +Director of Engineering: +Jim Fournier + +Manager, X Window System: +Matt Landau, emeritus + +Technical Director, X Window System: +Ralph Swick + +Technical Staff, X Window System: + +Donna Converse, emeritus +Stephen Gildea, emeritus +Kaleb Keithley +Arnaud Le Hors +Ralph Mor, emeritus +Ray Tice +Dave Wiggins, emeritus + +Managers, CDE Development: +Giora Guth +Peter Bohnert, emeritus + +Manager, CDE Quality Engineering: +David Brooks + +CDE Architects: +Kevin Samborn +Daniel Dardailler, emeritus + +Technical Staff, CDE Development: + +Art Barstow +Pascale Dardailler +David Kaelbling +Mitch Greess +Robert Seacord + +Technical Staff, CDE Quality Engineering: + +Chris Burleson +Tom Cavin +Sami Mohammed +Mark Schuldenfrei + +Manager, Systems Administration: +Kevin Ethier + +Technical Staff, Systems Administration: +Mike Donati +Amy Rich, emeritus +Anne Salemme +.fi + +.SH "BOARD OF DIRECTORS" +The X Consortium's activities and affairs were managed under the direction and +oversight of a Board of Directors, elected annually by the Members. The Board +was responsible for reviewing the achievements of the Consortium, approving +planned work, appointing a President and other officers of the Consortium, and +setting membership dues. The last Directors were: + +.nf +Robert W. Scheifler, President, X Consortium +Dr. Forest Baskett, Senior VP of R&D, Silicon Graphics Computer Systems +Harold D. Blair, Apogee International Corp. +Roger S. Gourd, Gourd & Associates +Dr. Robin Hillyard, Chairman and Chief Technical Officer, Novasoft Systems +Don McGovern, General Operations Manager and Executive Dir., Hewlett Packard +Peter J. Shaw, Senior VP, NetManage +Michael Tobias, President, Tech-Source, Inc. +.fi + +.SH "ADDRESS" +To reach the X Consortium public Wide World Web server, use the URL: +http://www.x.org/ +.PP +To reach the X Consortium public ftp machine, use anonymous ftp to: +ftp.x.org + +.SH "FULL MEMBERS" + +.nf +Adobe Systems Inc. +Cray Research, Inc. +Digital Equipment Corp. +Fujitsu Limited +Hewlett-Packard Company +Hitachi Ltd. +IBM Corporation +Megatek Corp. +Motorola, Inc. +NEC Corporation +Novell, Inc. +Oki Electric Industry Co., Ltd. +OMRON Corporation +SCO, Inc. +Siemens Nixdorf Informationssysteme AG +Silicon Graphics, Inc. +Sony Corporation +Sun Microsystems, Inc. +Tektronix, Inc. +.fi + +.SH "ASSOCIATE MEMBERS" + +.nf +Boundless Technologies +Hummingbird Communications Ltd. +Insignia Solutions, Ltd. +Mercury Interactive Corp. +NetManage, Inc. +Network Computing Devices +VisiCom Laboratories, Inc. +Walker Richer & Quinn, Inc. +.fi + +.SH "END USERS" + +.nf +Hughes Aircraft Company +.fi + +.SH "AFFILIATE MEMBERS" + +.nf +ASTEC, Inc. +BARCO Chromatics, Inc. +CenterLine Software, Inc. +CliniComp, Intl. +Component Integration Laboratories, Inc. +Draper Laboratory. +Electronic Book Technologies, Inc. +Gallium Software, Inc. +Georgia Institiute of Technology +Human Designed Systems, Inc. +INRIA \- Institut National de Recherche en Informatique et en Automatique +Integrated Computer Solutions, Inc. +Investment Management Services, Inc. +Jupiter Systems +KL Group Inc. +Massachusetts Institute of Technology +Metheus Corporation +Metro Link, Inc. +Object Management Group, Inc. +Open Software Foundation +Performance Awareness Corp. +Peritek Corp. +Petrotechnical Open Software Corp. +Point Technologies, Inc. +Shiman Associates, Inc. +Smithsonian Astrophysical Observatory. +Software Development Corp. +SOUM Corporation +Spectragraphics Corp. +Tech-Source, Inc. +TriTeal Corp. +White Pine Software, Inc. +World Wide Web Consortium. +The XFree86 Project, Inc. +X Inside, Inc. +.fi diff --git a/doc/xorg-docs/man/general/Makefile.am b/doc/xorg-docs/man/general/Makefile.am new file mode 100644 index 000000000..35a65f870 --- /dev/null +++ b/doc/xorg-docs/man/general/Makefile.am @@ -0,0 +1,57 @@ +# Copyright 2005 Red Hat, Inc. +# +# Permission to use, copy, modify, distribute, and sell this software +# and its documentation for any purpose is hereby granted without fee, +# provided that the above copyright notice appear in all copies and +# that both that copyright notice and this permission notice appear in +# supporting documentation, and that the name of Red Hat not be used in +# advertising or publicity pertaining to distribution of the software +# without specific, written prior permission. Red Hat makes no +# representations about the suitability of this software for any +# purpose. It is provided "as is" without express or implied warranty. +# +# RED HAT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, +# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN +# NO EVENT SHALL RED HAT BE LIABLE FOR ANY SPECIAL, INDIRECT OR +# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS +# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE +# USE OR PERFORMANCE OF THIS SOFTWARE. +# +# Process this file with autoconf to create configure. + +miscmandir = $(MISC_MAN_DIR) + +miscman_PRE = \ + Consortium.man \ + security.man \ + Standards.man \ + X.man \ + XOrgFoundation.man \ + Xprint.man \ + XProjectTeam.man + +miscman_DATA = $(miscman_PRE:man=@MISC_MAN_SUFFIX@) + +CLEANFILES = $(miscman_DATA) + +SED = sed + +# Strings to replace in man pages +XORGRELSTRING = @PACKAGE_STRING@ + XORGMANNAME = X Version 11 + +MAN_SUBSTS = \ + -e 's|__vendorversion__|"$(XORGRELSTRING)" "$(XORGMANNAME)"|' \ + -e 's|__xorgversion__|"$(XORGRELSTRING)" "$(XORGMANNAME)"|' \ + -e 's|__projectroot__|$(prefix)|g' \ + -e 's|__appmansuffix__|$(APP_MAN_SUFFIX)|g' \ + -e 's|__libmansuffix__|$(APP_LIB_SUFFIX)|g' \ + -e 's|__miscmansuffix__|$(MISC_MAN_SUFFIX)|g' + +SUFFIXES = .$(MISC_MAN_SUFFIX) .man + +.man.$(MISC_MAN_SUFFIX): + sed $(MAN_SUBSTS) < $< > $@ + +EXTRA_DIST = $(miscman_PRE) Xprint.sgml diff --git a/doc/xorg-docs/man/general/Standards.man b/doc/xorg-docs/man/general/Standards.man new file mode 100644 index 000000000..d904efddb --- /dev/null +++ b/doc/xorg-docs/man/general/Standards.man @@ -0,0 +1,435 @@ +.\" $Xorg: Standards.cpp,v 1.3 2000/08/17 19:42:04 cpqbld Exp $ +.\" $XdotOrg: xc/doc/man/general/Standards.man,v 1.3 2004/09/03 16:18:18 kem Exp $ +.\" Copyright (c) 1993, 1994, 1996, 2004 The Open Group +.\" +.\" All rights reserved. +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, and/or sell copies of the Software, and to permit persons +.\" to whom the Software is furnished to do so, provided that the above +.\" copyright notice(s) and this permission notice appear in all copies of +.\" the Software and that both the above copyright notice(s) and this +.\" permission notice appear in supporting documentation. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR +.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL +.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Except as contained in this notice, the name of a copyright holder +.\" shall not be used in advertising or otherwise to promote the sale, use +.\" or other dealings in this Software without prior written authorization +.\" of the copyright holder. +.\" +.\" X Window System is a trademark of The Open Group. +.\" +.TH XSTANDARDS __miscmansuffix__ __xorgversion__ +.SH NAME +XStandards \- X Window System Standards and Specifications +.SH SYNOPSIS +The major goal of the X Consortium was to promote cooperation within the +computer industry in the creation of standard software interfaces at +all layers in the X Window System environment. +The X Consortium produced standards - documents which +defined network protocols, programming interfaces, and +other aspects of the X environment. These standards +continue to exist in the X.Org Foundation releases. +The X.Org Foundation also produces specifications. +Like X Window System Standards, these are documents +which define network protocols, programming interfaces, +and other aspects of the X environment. Under the aegis +of The Open Group, X Window System standards, X.Org Foundation +specifications, and other specifications are the +basis for portions of The Open Group's various CAE +specifications. +.PP +The status of various standards, specifications, and +the software in the X11R7.0 distribution, is explained below. +.SH STANDARDS +The following documents are X Window System standards: +.nf + +X Window System Protocol +X Version 11, Release 7.0 +Robert W. Scheifler + +Xlib \- C Language X Interface +X Version 11, Release 7.0 +James Gettys, Robert W. Scheifler, Ron Newman + +X Toolkit Intrinsics \- C Language Interface +X Version 11, Release 7.0 +Joel McCormack, Paul Asente, Ralph R. Swick, Donna Converse + +Bitmap Distribution Format +Version 2.1 +X Version 11, Release 7.0 + +Inter-Client Communication Conventions Manual +Version 2.0 +X Version 11, Release 7.0 +David Rosenthal, Stuart W. Marks + +Compound Text Encoding +Version 1.1 +X Version 11, Release 7.0 +Robert W. Scheifler + +X Logical Font Description Conventions +Version 1.5 +X Version 11, Release 7.0 +Jim Flowers, Stephen Gildea + +X Display Manager Control Protocol +Version 1.1 +X Version 11, Release 7.0 +Keith Packard + +X11 Nonrectangular Window Shape Extension +Version 1.0.1 +X Version 11, Release 7.0 +Keith Packard + +X11 Input Extension Protocol Specification +Version 1.0 +X Version 11, Release 7.0 +George Sachs, Mark Patrick + +X11 Input Extension Library Specification +X Version 11, Release 7.0 +Mark Patrick, George Sachs + +The X Font Service Protocol +Version 2.0 +X Version 11, Release 7.0 +Jim Fulton + +Inter-Client Exchange (ICE) Protocol +Version 1.0 +X Version 11, Release 7.0 +Robert Scheifler, Jordan Brown + +Inter-Client Exchange (ICE) Library +Version 1.0 +X Version 11, Release 7.0 +Ralph Mor + +X Session Management Protocol +Version 1.0 +X Version 11, Release 7.0 +Mike Wexler + +X Session Management Library +Version 1.0 +X Version 11, Release 7.0 +Ralph Mor + +The Input Method Protocol +Version 1.0 +X Version 11, Release 7.0 +Masahiko Narita, Hideki Hiura + +X Synchronization Extension +Version 3.0 +X Version 11, Release 7.0 +Tim Glauert, Dave Carver, Jim Gettys, David P. Wiggins + +XTEST Extension +Version 2.2 +Kieron Drake + +Big Requests Extension +Version 2.0 +X Version 11, Release 7.0 +Bob Scheifler + +XC-MISC Extension +Version 1.1 +X Version 11, Release 7.0 +Bob Scheifler, Dave Wiggins + +Double Buffer Extension +Version 1.0 +Ian Elliott, David P. Wiggins + +Record Extension Protocol +Version 1.13 +Martha Zimet, Stephen Gildea + +Record Extension Library +Version 1.13 +Martha Zimet, Stephen Gildea + +X Keyboard Extension Protocol +X Version 11, Release 7.0 +Erik Fortune + +X Keyboard Extension Library +X Version 11, Release 7.0 +Amber J. Benson, Gary Aitken, Erik Fortune, Donna Converse, +George Sachs, and Will Walker + +X Print Extension Protocol +X Version 11, Release 7.0 + +X Print Extension Library +X Version 11, Release 7.0 + +X Application Group Extension Protocol and Library +Version 1.0 +X Version 11, Release 7.0 +Kaleb Keithley + +X Security Extension Protocol and Library +Version 4.0 +X Version 11, Release 7.0 +Dave Wiggins + +X Proxy Manager Protocol +X Version 11, Release 7.0 +Ralph Swick + +LBX Extension Protocol and Library +X Version 11, Release 7.0 +Keith Packard, Dave Lemke, Donna Converse, Ralph Mor, Ray Tice + +Remote Execution MIME Type +Version 1.0 +X Version 11, Release 7.0 +Arnaud Le Hors +.fi +.SH SPECIFICATIONS +The following documents are X Project Team specifications: +.nf + +Colormap Utilization Policy and Extension +Version 1.0 +Kaleb Keithley + +Extended Visual Information Extension +Version 1.0 +Peter Daifuku + +X Display Power Management (DPMS) Extension Protocol and Library +Version 1.0 +Rob Lembree + +.SH "INCLUDE FILES" +The following include files are part of the Xlib standard. +.PP +.nf +<X11/cursorfont.h> +<X11/keysym.h> +<X11/keysymdef.h> +<X11/X.h> +<X11/Xatom.h> +<X11/Xcms.h> +<X11/Xlib.h> +<X11/Xlibint.h> +<X11/Xproto.h> +<X11/Xprotostr.h> +<X11/Xresource.h> +<X11/Xutil.h> +<X11/X10.h> +.fi +.PP +The following include files are part of the X Toolkit Intrinsics standard. +.PP +.nf +<X11/Composite.h> +<X11/CompositeP.h> +<X11/Constraint.h> +<X11/ConstrainP.h> +<X11/Core.h> +<X11/CoreP.h> +<X11/Intrinsic.h> +<X11/IntrinsicP.h> +<X11/Object.h> +<X11/ObjectP.h> +<X11/RectObj.h> +<X11/RectObjP.h> +<X11/Shell.h> +<X11/ShellP.h> +<X11/StringDefs.h> +<X11/Vendor.h> +<X11/VendorP.h> +.fi +.PP +The following include file is part of the +Nonrectangular Window Shape Extension standard. +.PP +.nf +<X11/extensions/shape.h> +.fi +.PP +The following include files are part of the X Input Extension standard. +.PP +.nf +<X11/extensions/XI.h> +<X11/extensions/XInput.h> +<X11/extensions/XIproto.h> +.fi +.PP +The following include files are part of the ICElib standard. +.PP +.nf +<X11/ICE/ICE.h> +<X11/ICE/ICEconn.h> +<X11/ICE/ICElib.h> +<X11/ICE/ICEmsg.h> +<X11/ICE/ICEproto.h> +<X11/ICE/ICEutil.h> +.fi +.PP +The following include files are part of the SMlib standard. +.PP +.nf +<X11/SM/SM.h> +<X11/SM/SMlib.h> +<X11/SM/SMproto.h> +.fi +.PP +The following include file is part of the Synchronization standard. +.PP +.nf +<X11/extensions/sync.h> +.fi +.PP +The following include file is part of the XTEST standard. +.PP +.nf +<X11/extensions/XTest.h> +.fi +.PP +The following include file is part of the Double Buffer Extension standard. +.PP +.nf +<X11/extensions/Xdbe.h> +.fi +.PP +The following include file is part of the Record Library standard. +.PP +.nf +<X11/extensions/record.h> +.fi +.PP +The following include files are part of the X Keyboard Extension Library +standard. +.PP +.nf +\" some subset of... +<X11/XKBlib.h> +<X11/extensions/XKB.h> +<X11/extensions/XKBproto.h> +<X11/extensions/XKBstr.h> +<X11/extensions/XKBgeom.h> +.fi +.PP +The following include files are part of the X Print Extension Library +standard. +.PP +.nf +<X11/extensions/Print.h> +<X11/extensions/Printstr.h> +.fi +.PP +The following include files are part of the X Application Group Extension +Library standard. +.PP +.nf +<X11/extensions/Xag.h> +<X11/extensions/Xagstr.h> +.fi +.PP +The following include files are part of the X Security Extension Library +standard. +.PP +.nf +<X11/extensions/security.h> +<X11/extensions/securstr.h> +.fi +.PP +The following include files are part of the LBX Extension library standard. +.PP +.nf +\" some subset of... +<X11/extensions/XLbx.h> +<X11/extensions/lbxbuf.h> +<X11/extensions/lbxbufstr.h> +<X11/extensions/lbxdeltastr.h> +<X11/extensions/lbximage.h> +<X11/extensions/lbxopts.h> +<X11/extensions/lbxstr.h> +<X11/extensions/lbxzlib.h> +.fi +.PP +The following include files are part of the Colormap Utilization +Policy and Extension specification. +.PP +.nf +<X11/extensions/Xcup.h> +<X11/extensions/Xcupstr.h> +.fi +.PP +The following include files are part of the Extended Visual +Information specification. +.PP +.nf +<X11/extensions/XEVI.h> +<X11/extensions/XEVIstr.h> +.fi +.PP +The following include files are part of the X Display Management +Signaling Extension specification. +.PP +.nf +<X11/extensions/dpms.h> +<X11/extensions/dpmsstr.h> +.fi + +.SH "NON STANDARDS" +The X11R7.0 distribution contains \fIsample\fP implementations, not +\fIreference\fP implementations. Although much of the code is believed +to be correct, the code should be assumed to be in error wherever it +conflicts with the specification. +.PP +The only X Window System standards are the ones listed above. +No other documents, include files, or software in X11R7.0 carry special +status within the X Window System. For example, none of the following +are standards: +internal interfaces of the sample server; +the MIT-SHM extension; +the Athena Widget Set; +the Xmu library; +the Xau library; +the RGB database; +the X Locale database; +the fonts distributed with X11R7.0; +the applications distributed with X11R7.0; +the include files <X11/XWDFile.h>, <X11/Xfuncproto.h>, <X11/Xfuncs.h>, +<X11/Xosdefs.h>, <X11/Xos.h>, <X11/Xos_r.h>, <X11/Xwinsock.h>, and +<X11/Xthreads.h>; +the bitmap files in <X11/bitmaps>. +.PP +The Multi-Buffering extension was a draft standard of the +X Consortium but has been superseded by DBE as a standard. + +.SH "X REGISTRY" +The X.Org Foundation maintains a registry of certain X-related items, to +aid in avoiding conflicts and to aid in sharing of such items. +.PP +The registry is published as part of the X Window System software +release. +The latest version may also be found at +.nf + ftp://ftp.x.org/pub/DOCS/registry +.fi +The X Registry and the names in it are not X Window System standards. diff --git a/doc/xorg-docs/man/general/X.man b/doc/xorg-docs/man/general/X.man new file mode 100644 index 000000000..128506b68 --- /dev/null +++ b/doc/xorg-docs/man/general/X.man @@ -0,0 +1,1334 @@ +.\" $Xorg: X.cpp,v 1.3 2000/08/17 19:42:04 cpqbld Exp $ +.\" $XdotOrg: xc/doc/man/general/X.man,v 1.6 2004/12/08 13:42:01 ago Exp $ +.\" +.\" Copyright (c) 1994, 2004 The Open Group +.\" Copyright \(co 2000 The XFree86 Project, Inc. +.\" +.\" All rights reserved. +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, and/or sell copies of the Software, and to permit persons +.\" to whom the Software is furnished to do so, provided that the above +.\" copyright notice(s) and this permission notice appear in all copies of +.\" the Software and that both the above copyright notice(s) and this +.\" permission notice appear in supporting documentation. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR +.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL +.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Except as contained in this notice, the name of a copyright holder +.\" shall not be used in advertising or otherwise to promote the sale, use +.\" or other dealings in this Software without prior written authorization +.\" of the copyright holder. +.\" +.\" X Window System is a trademark of The Open Group. +.\" +.\" $XFree86: xc/doc/man/general/X.man,v 1.7 2001/10/01 13:43:56 eich Exp $ +.\" +.TH X __miscmansuffix__ __vendorversion__ +.SH NAME +X \- a portable, network-transparent window system +.SH SYNOPSIS +.PP +The X Window System is a network transparent window system which runs +on a wide range of computing and graphics machines. It should be +relatively straightforward to build the X.Org Foundation software +distribution on most ANSI C and POSIX compliant systems. Commercial +implementations are also available for a wide range of platforms. +.PP +The X.Org Foundation requests that the following names be used when +referring to this software: +.sp +.ce 5 +X +.br +X Window System +.br +X Version 11 +.br +X Window System, Version 11 +.br +X11 +.PP +.I "X Window System" +is a trademark of The Open Group. +.SH DESCRIPTION +X Window System servers run on computers with bitmap displays. +The server distributes user input to and accepts output requests from various +client programs through a variety of different interprocess +communication channels. Although the most common case is for the client +programs to be +running on the same machine as the server, clients can be run transparently +from other machines (including machines with different architectures and +operating systems) as well. +.PP +X supports overlapping hierarchical subwindows and text and +graphics operations, on both monochrome and color +displays. +For a full explanation of the functions that are available, see +the \fIXlib - C Language X Interface\fP manual, +the \fIX Window System Protocol\fP specification, +the \fIX Toolkit Intrinsics - C Language Interface\fP manual, +and various toolkit documents. +.PP +The number of programs that use \fIX\fP is quite large. +Programs provided in the core X.Org Foundation distribution include: +a terminal emulator, \fIxterm\fP; +a window manager, \fItwm\fP; +a display manager, \fIxdm\fP; +a console redirect program, \fIxconsole\fP; +a mail interface, \fIxmh\fP; +a bitmap editor, \fIbitmap\fP; +resource listing/manipulation tools, \fIappres\fP, \fIeditres\fP; +access control programs, \fIxauth\fP, \fIxhost\fP, and \fIiceauth\fP; +user preference setting programs, \fIxrdb\fP, \fIxcmsdb\fP, +\fIxset\fP, \fIxsetroot\fP, \fIxstdcmap\fP, and \fIxmodmap\fP; +clocks, \fIxclock\fP and \fIoclock\fP; +a font displayer, (\fIxfd\fP; +utilities for listing information about fonts, windows, and displays, +\fIxlsfonts\fP, \fIxwininfo\fP, \fIxlsclients\fP, +\fIxdpyinfo\fP, \fIxlsatoms\fP, and \fIxprop\fP; +screen image manipulation utilities, \fIxwd\fP, \fIxwud\fP, and \fIxmag\fP; +a performance measurement utility, \fIx11perf\fP; +a font compiler, \fIbdftopcf\fP; +a font server and related utilities, \fIxfs\fP, \fIfsinfo\fP, \fIfslsfonts\fP, \fIfstobdf\fP; +a display server and related utilities, \fIXserver\fP, \fIrgb\fP, \fImkfontdir\fP; +a print server and related utilities, \fIXprt\fP, \fIxplsprinters\fP, and \fIxprehashprinterlist\fP; +remote execution utilities, \fIrstart\fP and \fIxon\fP; +a clipboard manager, \fIxclipboard\fP; +keyboard description compiler and related utilities, \fIxkbcomp\fP, \fIsetxkbmap\fP +\fIxkbprint\fP, \fIxkbbell\fP, \fIxkbevd\fP, \fIxkbvleds\fP, and \fIxkbwatch\fP; +a utility to terminate clients, \fIxkill\fP; +an optimized X protocol proxy, \fIlbxproxy\fP; +a firewall security proxy, \fIxfwp\fP; +a proxy manager to control them, \fIproxymngr\fP; +a utility to find proxies, \fIxfindproxy\fP; +web browser plug-ins, \fIlibxrx.so\fP and \fIlibxrxnest.so\fP; +an RX MIME-type helper program, \fIxrx\fP; +and a utility to cause part or all of the screen to be redrawn, \fIxrefresh\fP. +.PP +Many other utilities, window managers, games, toolkits, etc. are included +as user-contributed software in the X.Org Foundation distribution, or are +available on the Internet. +See your site administrator for details. +.SH "STARTING UP" +.PP +There are two main ways of getting the X server and an initial set of +client applications started. The particular method used depends on what +operating system you are running and whether or not you use other window +systems in addition to X. +.TP 8 +.B "\fIxdm\fP (the X Display Manager)" +If you want to always have X running on your display, your site administrator +can set your machine up to use the X Display Manager \fIxdm\fP. This program +is typically started by the system at boot time and takes care of keeping the +server running and getting users logged in. If you are running +\fIxdm\fP, you will see a window on the screen welcoming you to the system and +asking for your username and password. Simply type them in as you would at +a normal terminal, pressing the Return key after each. If you make a mistake, +\fIxdm\fP will display an error message and ask you to try again. After you +have successfully logged in, \fIxdm\fP will start up your X environment. By +default, if you have an executable file named \fI.xsession\fP in your +home directory, +\fIxdm\fP will treat it as a program (or shell script) to run to start up +your initial clients (such as terminal emulators, clocks, a window manager, +user settings for things like the background, the speed of the pointer, etc.). +Your site administrator can provide details. +.TP 8 +.B "\fIxinit\fP (run manually from the shell)" +Sites that support more than one window system might choose to use the +\fIxinit\fP program for starting X manually. If this is true for your +machine, your site administrator will probably have provided a program +named "x11", "startx", or "xstart" that will do site-specific initialization +(such as loading convenient default resources, running a window manager, +displaying a clock, and starting several terminal emulators) in a nice +way. If not, you can build such a script using the \fIxinit\fP program. +This utility simply runs one user-specified program to start the server, +runs another to start up any desired clients, and then waits for either to +finish. Since either or both of the user-specified programs may be a shell +script, this gives substantial flexibility at the expense of a +nice interface. For this reason, \fIxinit\fP is not intended for end users. +.SH "DISPLAY NAMES" +.PP +From the user's perspective, every X server has a \fIdisplay name\fP of the +form: +.sp +.ce 1 +\fIhostname:displaynumber.screennumber\fP +.sp +This information is used by the application to determine how it should +connect to the server and which screen it should use by default +(on displays with multiple monitors): +.TP 8 +.I hostname +The \fIhostname\fP specifies the name of the machine to which the display is +physically connected. If the hostname is not given, the most efficient way of +communicating to a server on the same machine will be used. +.TP 8 +.I displaynumber +The phrase "display" is usually used to refer to collection of monitors that +share a common keyboard and pointer (mouse, tablet, etc.). Most workstations +tend to only have one keyboard, and therefore, only one display. Larger, +multi-user +systems, however, frequently have several displays so that more than +one person can be doing graphics work at once. To avoid confusion, each +display on a machine is assigned a \fIdisplay number\fP (beginning at 0) +when the X server for that display is started. The display number must always +be given in a display name. +.TP 8 +.I screennumber +Some displays share a single keyboard and pointer among two or more monitors. +Since each monitor has its own set of windows, each screen is assigned a +\fIscreen number\fP (beginning at 0) when the X server for that display is +started. If the screen number is not given, screen 0 will be used. +.PP +On POSIX systems, the default display name is stored +in your DISPLAY environment variable. This variable is set automatically +by the \fIxterm\fP terminal emulator. However, when you log into another +machine on a network, you will need to set DISPLAY by hand to point to your +display. For example, +.sp +.nf + % setenv DISPLAY myws:0 + $ DISPLAY=myws:0; export DISPLAY +.fi +The \fIxon\fP script can be used to start an X program on a remote machine; +it automatically sets the DISPLAY variable correctly. +.PP +Finally, most X programs accept a command line option of +\fB-display \fIdisplayname\fR to temporarily override the contents of +DISPLAY. This is most commonly used to pop windows on another person's +screen or as part of a "remote shell" command to start an xterm pointing back +to your display. For example, +.sp +.nf + % xeyes -display joesws:0 -geometry 1000x1000+0+0 + % rsh big xterm -display myws:0 -ls </dev/null & +.fi +.PP +X servers listen for connections on a variety of different +communications channels (network byte streams, shared memory, etc.). +Since there can be more than one way of contacting a given server, +The \fIhostname\fP part of the display name is used to determine the +type of channel +(also called a transport layer) to be used. X servers generally +support the following types of connections: +.TP 8 +.I "local" +.br +The hostname part of the display name should be the empty string. +For example: \fI:0\fP, \fI:1\fP, and \fI:0.1\fP. The most efficient +local transport will be chosen. +.TP 8 +.I TCP\/IP +.br +The hostname part of the display name should be the server machine's +IP address name. Full Internet names, abbreviated names, and IP addresses +are all allowed. For example: \fIx.org:0\fP, \fIexpo:0\fP, +\fI198.112.45.11:0\fP, \fIbigmachine:1\fP, and \fIhydra:0.1\fP. +.TP 8 +.I DECnet +.br +The hostname part of the display name should be the server machine's +nodename, followed by two colons instead of one. +For example: \fImyws::0\fP, \fIbig::1\fP, and \fIhydra::0.1\fP. +.PP +.SH "ACCESS CONTROL" +An X server can use several types of access control. Mechanisms provided +in Release 6 are: +.nf +.br +.ta 3.4i + Host Access Simple host-based access control. + MIT-MAGIC-COOKIE-1 Shared plain-text "cookies". + XDM-AUTHORIZATION-1 Secure DES based private-keys. + SUN-DES-1 Based on Sun's secure rpc system. + MIT-KERBEROS-5 Kerberos Version 5 user-to-user. +.fi +.PP +\fIXdm\fP initializes access control for the server and also places +authorization information in a file accessible to the user. +Normally, the list of hosts from +which connections are always accepted should be empty, so that only clients +with are explicitly authorized can connect to the display. When you add +entries to the host list (with \fIxhost\fP), the server no longer performs any +authorization on connections from those machines. Be careful with this. +.PP +The file from which \fIXlib\fP extracts authorization data can be +specified with the environment variable \fBXAUTHORITY\fP, and defaults to +the file \fB.Xauthority\fP in the home directory. \fIXdm\fP uses +\fB$HOME/.Xauthority\fP and will create it or merge in authorization records +if it already exists when a user logs in. +.PP +If you use several machines and share a common home directory +across all of the machines by means of a network file system, +you never really have to worry about authorization files, +the system should work correctly by default. +Otherwise, as the authorization files are machine-independent, +you can simply copy the files to share them. +To manage authorization files, use \fIxauth\fP. +This program allows you to extract +records and insert them into other files. Using this, you can send +authorization to remote machines when you login, +if the remote machine does not share a common home directory with +your local machine. +Note that authorization information transmitted +``in the clear'' through a network file system or +using \fIftp\fP or \fIrcp\fP can be ``stolen'' +by a network eavesdropper, and as such may enable unauthorized access. +In many environments, this level of security is not a concern, but if it is, +you need to know the exact semantics of the particular authorization +data to know if this is actually a problem. +.PP +For more information on access control, see the \fIXsecurity\fP manual page. +.SH "GEOMETRY SPECIFICATIONS" +One of the advantages of using window systems instead of +hardwired terminals is that +applications don't have to be restricted to a particular size or location +on the screen. +Although the layout of windows on a display is controlled +by the window manager that the user is running (described below), +most X programs accept +a command line argument of the form \fB-geometry \fIWIDTHxHEIGHT+XOFF+YOFF\fR +(where \fIWIDTH\fP, \fIHEIGHT\fP, \fIXOFF\fP, and \fIYOFF\fP are numbers) +for specifying a preferred size and location for this application's main +window. +.PP +The \fIWIDTH\fP and \fIHEIGHT\fP parts of the geometry specification are +usually measured in either pixels or characters, depending on the application. +The \fIXOFF\fP and \fIYOFF\fP parts are measured in pixels and are used to +specify the distance of the window from the left or right and top and bottom +edges of the screen, respectively. Both types of offsets are measured from the +indicated edge of the screen to the corresponding edge of the window. The X +offset may be specified in the following ways: +.TP 8 +.I +XOFF +The left edge of the window is to be placed \fIXOFF\fP pixels in from the +left edge of the screen (i.e., the X coordinate of the window's origin will be +\fIXOFF\fP). \fIXOFF\fP may be negative, in which case the window's left edge +will be off the screen. +.TP 8 +.I -XOFF +The right edge of the window is to be placed \fIXOFF\fP pixels in from the +right edge of the screen. \fIXOFF\fP may be negative, in which case the +window's right edge will be off the screen. +.PP +The Y offset has similar meanings: +.TP 8 +.I +YOFF +The top edge of the window is to be \fIYOFF\fP pixels below the +top edge of the screen (i.e., the Y coordinate of the window's origin will be +\fIYOFF\fP). \fIYOFF\fP may be negative, in which case the window's top edge +will be off the screen. +.TP 8 +.I -YOFF +The bottom edge of the window is to be \fIYOFF\fP pixels above the +bottom edge of the screen. \fIYOFF\fP may be negative, in which case +the window's bottom edge will be off the screen. +.PP +Offsets must be given as pairs; in other words, in order to specify either +\fIXOFF\fP or \fIYOFF\fP both must be present. Windows can be placed in the +four corners of the screen using the following specifications: +.TP 8 +.I +0+0 +upper left hand corner. +.TP 8 +.I -0+0 +upper right hand corner. +.TP 8 +.I -0-0 +lower right hand corner. +.TP 8 +.I +0-0 +lower left hand corner. +.PP +In the following examples, a terminal emulator is placed in roughly +the center of the screen and +a load average monitor, mailbox, and clock are placed in the upper right +hand corner: +.sp +.nf + xterm -fn 6x10 -geometry 80x24+30+200 & + xclock -geometry 48x48-0+0 & + xload -geometry 48x48-96+0 & + xbiff -geometry 48x48-48+0 & +.fi +.PP +.SH "WINDOW MANAGERS" +The layout of windows on the screen is controlled by special programs called +\fIwindow managers\fP. Although many window managers will honor geometry +specifications as given, others may choose to ignore them (requiring the user +to explicitly draw the window's region on the screen with the pointer, for +example). +.PP +Since window managers are regular (albeit complex) client programs, +a variety of different user interfaces can be built. The X.Org Foundation distribution +comes with a window manager named \fItwm\fP which supports overlapping windows, +popup menus, point-and-click or click-to-type input models, title bars, nice +icons (and an icon manager for those who don't like separate icon windows). +.PP +See the user-contributed software in the X.Org Foundation distribution for other +popular window managers. +.SH "FONT NAMES" +Collections of characters for displaying text and symbols in X are known as +\fIfonts\fP. A font typically contains images that share a common appearance +and look nice together (for example, a single size, boldness, slant, and +character set). Similarly, collections of fonts that are based on a common +type face (the variations are usually called roman, bold, italic, bold italic, +oblique, and bold oblique) are called \fIfamilies\fP. +.PP +Fonts come in various sizes. The X server supports \fIscalable\fP fonts, +meaning it is possible to create a font of arbitrary size from a single +source for the font. The server supports scaling from \fIoutline\fP +fonts and \fIbitmap\fP fonts. Scaling from outline fonts usually produces +significantly better results than scaling from bitmap fonts. +.PP +An X server can obtain fonts from individual files stored in directories +in the file system, or from one or more font servers, +or from a mixtures of directories and font servers. +The list of places the server looks when trying to find +a font is controlled by its \fIfont path\fP. Although most installations +will choose to have the server start up with all of the commonly used font +directories in the font path, the font path can be changed at any time +with the \fIxset\fP program. +However, it is important to remember that the directory names are +on the \fBserver\fP's machine, not on the application's. +.PP +Bitmap font files are usually created by compiling a textual font description +into binary form, using \fIbdftopcf\fP. +Font databases are created by running the \fImkfontdir\fP program in the +directory containing the source or compiled versions of the fonts. +Whenever fonts are added to a directory, \fImkfontdir\fP should be rerun +so that the server can find the new fonts. To make the server reread the +font database, reset the font path with the \fIxset\fP program. For example, +to add a font to a private directory, the following commands could be used: +.sp +.nf + % cp newfont.pcf ~/myfonts + % mkfontdir ~/myfonts + % xset fp rehash +.fi +.PP +The \fIxfontsel\fP and \fIxlsfonts\fP programs can be used to browse +through the fonts available on a server. +Font names tend to be fairly long as they contain all of the information +needed to uniquely identify individual fonts. However, the X server +supports wildcarding of font names, so the full specification +.sp +.nf + \fI-adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-1\fP +.fi +.sp +might be abbreviated as: +.sp +.nf + \fI-*-courier-medium-r-normal--*-100-*-*-*-*-iso8859-1\fP +.fi +.PP +Because the shell also has special meanings for \fI*\fP and \fI?\fP, +wildcarded font names should be quoted: +.sp +.nf + % xlsfonts -fn '-*-courier-medium-r-normal--*-100-*-*-*-*-*-*' +.fi +.PP +The \fIxlsfonts\fP program can be used to list all of the fonts that +match a given pattern. With no arguments, it lists all available fonts. +This will usually list the same font at many different sizes. To see +just the base scalable font names, try using one of the following patterns: +.sp +.nf + \fI-*-*-*-*-*-*-0-0-0-0-*-0-*-*\fP + \fI-*-*-*-*-*-*-0-0-75-75-*-0-*-*\fP + \fI-*-*-*-*-*-*-0-0-100-100-*-0-*-*\fP +.fi +.PP +To convert one of the resulting names into a font at a specific size, +replace one of the first two zeros with a nonzero value. +The field containing the first zero is for the pixel size; replace it +with a specific height in pixels to name a font at that size. +Alternatively, the field containing the second zero is for the point size; +replace it with a specific size in decipoints (there are 722.7 decipoints to +the inch) to name a font at that size. +The last zero is an average width field, measured in tenths of pixels; +some servers will anamorphically scale if this value is specified. +.SH "FONT SERVER NAMES" +One of the following forms can be used to name a font server that +accepts TCP connections: +.sp +.nf + tcp/\fIhostname\fP:\fIport\fP + tcp/\fIhostname\fP:\fIport\fP/\fIcataloguelist\fP +.fi +.PP +The \fIhostname\fP specifies the name (or decimal numeric address) +of the machine on which the font server is running. The \fIport\fP +is the decimal TCP port on which the font server is listening for connections. +The \fIcataloguelist\fP specifies a list of catalogue names, +with '+' as a separator. +.PP +Examples: \fItcp/x.org:7100\fP, \fItcp/198.112.45.11:7100/all\fP. +.PP +One of the following forms can be used to name a font server that +accepts DECnet connections: +.sp +.nf + decnet/\fInodename\fP::font$\fIobjname\fP + decnet/\fInodename\fP::font$\fIobjname\fP/\fIcataloguelist\fP +.fi +.PP +The \fInodename\fP specifies the name (or decimal numeric address) +of the machine on which the font server is running. +The \fIobjname\fP is a normal, case-insensitive DECnet object name. +The \fIcataloguelist\fP specifies a list of catalogue names, +with '+' as a separator. +.PP +Examples: \fIDECnet/SRVNOD::FONT$DEFAULT\fP, \fIdecnet/44.70::font$special/symbols\fP. +.SH "COLOR NAMES" +Most applications provide ways of tailoring (usually through resources or +command line arguments) the colors of various elements +in the text and graphics they display. +A color can be specified either by an abstract color name, +or by a numerical color specification. +The numerical specification can identify a color in either +device-dependent (RGB) or device-independent terms. +Color strings are case-insensitive. +.PP +X supports the use of abstract color names, for example, "red", "blue". +A value for this abstract name is obtained by searching one or more color +name databases. +\fIXlib\fP first searches zero or more client-side databases; +the number, location, and content of these databases is +implementation dependent. +If the name is not found, the color is looked up in the +X server's database. +The text form of this database is commonly stored in the file +\fI\__projectroot__/lib/X11/rgb.txt\fP. +.PP +A numerical color specification +consists of a color space name and a set of values in the following syntax: +.sp +.nf + \fI<color_space_name>\fP:\fI<value>/.../<value>\fP +.fi +.PP +An RGB Device specification is identified by +the prefix "rgb:" and has the following syntax: +.sp +.nf + rgb:\fI<red>/<green>/<blue>\fP + + \fI<red>\fP, \fI<green>\fP, \fI<blue>\fP := \fIh\fP | \fIhh\fP | \fIhhh\fP | \fIhhhh\fP + \fIh\fP := single hexadecimal digits +.fi +Note that \fIh\fP indicates the value scaled in 4 bits, +\fIhh\fP the value scaled in 8 bits, +\fIhhh\fP the value scaled in 12 bits, +and \fIhhhh\fP the value scaled in 16 bits, respectively. +These values are passed directly to the X server, +and are assumed to be gamma corrected. +.PP +The eight primary colors can be represented as: +.sp +.ta 2.5i +.nf + black rgb:0/0/0 + red rgb:ffff/0/0 + green rgb:0/ffff/0 + blue rgb:0/0/ffff + yellow rgb:ffff/ffff/0 + magenta rgb:ffff/0/ffff + cyan rgb:0/ffff/ffff + white rgb:ffff/ffff/ffff +.fi +.PP +For backward compatibility, an older syntax for RGB Device is +supported, but its continued use is not encouraged. +The syntax is an initial sharp sign character followed by +a numeric specification, in one of the following formats: +.sp +.ta 3i +.nf +\& #RGB (4 bits each) +\& #RRGGBB (8 bits each) +\& #RRRGGGBBB (12 bits each) +\& #RRRRGGGGBBBB (16 bits each) +.fi +.PP +The R, G, and B represent single hexadecimal digits. +When fewer than 16 bits each are specified, +they represent the most-significant bits of the value +(unlike the "rgb:" syntax, in which values are scaled). +For example, #3a7 is the same as #3000a0007000. +.PP +An RGB intensity specification is identified +by the prefix "rgbi:" and has the following syntax: +.sp +.nf + rgbi:\fI<red>/<green>/<blue>\fP +.fi +.PP +The red, green, and blue are floating point values +between 0.0 and 1.0, inclusive. +They represent linear intensity values, with +1.0 indicating full intensity, 0.5 half intensity, and so on. +These values will be gamma corrected by \fIXlib\fP +before being sent to the X server. +The input format for these values is an optional sign, +a string of numbers possibly containing a decimal point, +and an optional exponent field containing an E or e +followed by a possibly signed integer string. +.PP +The standard device-independent string specifications have +the following syntax: +.sp +.ta 3.5i +.nf + CIEXYZ:\fI<X>/<Y>/<Z>\fP (\fInone\fP, 1, \fInone\fP) + CIEuvY:\fI<u>/<v>/<Y>\fP (~.6, ~.6, 1) + CIExyY:\fI<x>/<y>/<Y>\fP (~.75, ~.85, 1) + CIELab:\fI<L>/<a>/<b>\fP (100, \fInone\fP, \fInone\fP) + CIELuv:\fI<L>/<u>/<v>\fP (100, \fInone\fP, \fInone\fP) + TekHVC:\fI<H>/<V>/<C>\fP (360, 100, 100) +.fi +.PP +All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are +floating point values. Some of the values are constrained to +be between zero and some upper bound; the upper bounds are +given in parentheses above. +The syntax for these values is an optional '+' or '-' sign, +a string of digits possibly containing a decimal point, +and an optional exponent field consisting of an 'E' or 'e' +followed by an optional '+' or '-' followed by a string of digits. +.PP +For more information on device independent color, +see the \fIXlib\fP reference manual. +.SH KEYBOARDS +.PP +The X keyboard model is broken into two layers: server-specific codes +(called \fIkeycodes\fP) which represent the physical keys, and +server-independent symbols (called \fIkeysyms\fP) which +represent the letters or words that appear on the keys. +Two tables are kept in the server for converting keycodes to keysyms: +.TP 8 +.I "modifier list" +Some keys (such as Shift, Control, and Caps Lock) are known as \fImodifier\fP +and are used to select different symbols that are attached to a single key +(such as Shift-a generates a capital A, and Control-l generates a control +character ^L). The server keeps a list of keycodes corresponding to the +various modifier keys. Whenever a key is pressed or released, the server +generates an \fIevent\fP that contains the keycode of the indicated key as +well as a mask that specifies which of the modifier keys are currently pressed. +Most servers set up this list to initially contain +the various shift, control, and shift lock keys on the keyboard. +.TP 8 +.I "keymap table" +Applications translate event keycodes and modifier masks into keysyms +using a \fIkeysym table\fP which contains one row for each keycode and one +column for various modifier states. This table is initialized by the server +to correspond to normal typewriter conventions. The exact semantics of +how the table is interpreted to produce keysyms depends on the particular +program, libraries, and language input method used, but the following +conventions for the first four keysyms in each row are generally adhered to: +.PP +The first four elements of the list are split into two groups of keysyms. +Group 1 contains the first and second keysyms; +Group 2 contains the third and fourth keysyms. +Within each group, +if the first element is alphabetic and the +the second element is the special keysym \fINoSymbol\fP, +then the group is treated as equivalent to a group in which +the first element is the lowercase letter and the second element +is the uppercase letter. +.PP +Switching between groups is controlled by the keysym named MODE SWITCH, +by attaching that keysym to some key and attaching +that key to any one of the modifiers Mod1 through Mod5. +This modifier is called the ``group modifier.'' +Group 1 is used when the group modifier is off, +and Group 2 is used when the group modifier is on. +.PP +Within a group, +the modifier state determines which keysym to use. +The first keysym is used when the Shift and Lock modifiers are off. +The second keysym is used when the Shift modifier is on, +when the Lock modifier is on and the second keysym is uppercase alphabetic, +or when the Lock modifier is on and is interpreted as ShiftLock. +Otherwise, when the Lock modifier is on and is interpreted as CapsLock, +the state of the Shift modifier is applied first to select a keysym; +but if that keysym is lowercase alphabetic, +then the corresponding uppercase keysym is used instead. +.SH OPTIONS +Most X programs attempt to use the same names for command line options and +arguments. All applications written with the X Toolkit Intrinsics +automatically accept the following options: +.TP 8 +.B \-display \fIdisplay\fP +This option specifies the name of the X server to use. +.TP 8 +.B \-geometry \fIgeometry\fP +This option specifies the initial size and location of the window. +.TP 8 +.B \-bg \fIcolor\fP, \fB\-background \fIcolor\fP +Either option specifies the color to use for the window background. +.TP 8 +.B \-bd \fIcolor\fP, \fB\-bordercolor \fIcolor\fP +Either option specifies the color to use for the window border. +.TP 8 +.B \-bw \fInumber\fP, \fB\-borderwidth \fInumber\fP +Either option specifies the width in pixels of the window border. +.TP 8 +.B \-fg \fIcolor\fP, \fB\-foreground \fIcolor\fP +Either option specifies the color to use for text or graphics. +.TP 8 +.B \-fn \fIfont\fP, \fB-font \fIfont\fP +Either option specifies the font to use for displaying text. +.TP 8 +.B \-iconic +.br +This option indicates that the user would prefer that the application's +windows initially not be visible as if the windows had be immediately +iconified by the user. Window managers may choose not to honor the +application's request. +.TP 8 +.B \-name +.br +This option specifies the name under which resources for the +application should be found. This option is useful in shell +aliases to distinguish between invocations of an application, +without resorting to creating links to alter the executable file name. +.TP 8 +.B \-rv\fP, \fB\-reverse\fP +Either option indicates that the program should simulate reverse video if +possible, often by swapping the foreground and background colors. Not all +programs honor this or implement it correctly. It is usually only used on +monochrome displays. +.TP 8 +.B \+rv +.br +This option indicates that the program should not simulate reverse video. +This is used to +override any defaults since reverse video doesn't always work properly. +.TP 8 +.B \-selectionTimeout +This option specifies the timeout in milliseconds within which two +communicating applications must respond to one another for a selection +request. +.TP 8 +.B \-synchronous +This option indicates that requests to the X server should be sent +synchronously, instead of asynchronously. Since +.I Xlib +normally buffers requests to the server, errors do not necessarily get reported +immediately after they occur. This option turns off the buffering so that +the application can be debugged. It should never be used with a working +program. +.TP 8 +.B \-title \fIstring\fP +This option specifies the title to be used for this window. This information +is sometimes +used by a window manager to provide some sort of header identifying the window. +.TP 8 +.B \-xnllanguage \fIlanguage[_territory][.codeset]\fP +This option specifies the language, territory, and codeset for use in +resolving resource and other filenames. +.TP 8 +.B \-xrm \fIresourcestring\fP +This option specifies a resource name and value to override any defaults. It +is also very useful for setting resources that don't have explicit command +line arguments. +.SH RESOURCES +To make the tailoring of applications to personal preferences easier, X +provides a mechanism for storing default values for program resources +(e.g. background color, window title, etc.) +Resources are specified as strings +that are read in from various places when an application is run. +Program components are named in a hierarchical fashion, +with each node in the hierarchy identified by a class and an instance name. +At the top level is the class and instance name of the application itself. +By convention, the class name of the application is the same as the program +name, but with the first letter capitalized (e.g. \fIBitmap\fP or \fIEmacs\fP) +although some programs that begin with the letter ``x'' also capitalize the +second letter for historical reasons. +.PP +The precise syntax for resources is: +.PP +.nf +.ta 1.8i 2.0i +ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line> +Comment = "!" {<any character except null or newline>} +IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace +FileName = <valid filename for operating system> +ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value +ResourceName = [Binding] {Component Binding} ComponentName +Binding = "\&." | "*" +WhiteSpace = {<space> | <horizontal tab>} +Component = "?" | ComponentName +ComponentName = NameChar {NameChar} +NameChar = "a"\-"z" | "A"\-"Z" | "0"\-"9" | "_" | "-" +Value = {<any character except null or unescaped newline>} +.fi +.PP +Elements separated by vertical bar (|) are alternatives. +Curly braces ({\&.\&.\&.}) indicate zero or more repetitions +of the enclosed elements. +Square brackets ([\&.\&.\&.]) indicate that the enclosed element is optional. +Quotes ("\&.\&.\&.") are used around literal characters. +.PP +IncludeFile lines are interpreted by replacing the line with the +contents of the specified file. The word "include" must be in lowercase. +The filename is interpreted relative to the directory of the file in +which the line occurs (for example, if the filename contains no +directory or contains a relative directory specification). +.PP +If a ResourceName contains a contiguous sequence of two or more Binding +characters, the sequence will be replaced with single "\&." character +if the sequence contains only "\&." characters, +otherwise the sequence will be replaced with a single "*" character. +.PP +A resource database never contains more than one entry for a given +ResourceName. If a resource file contains multiple lines with the +same ResourceName, the last line in the file is used. +.PP +Any whitespace character before or after the name or colon in a ResourceSpec +are ignored. +To allow a Value to begin with whitespace, +the two-character sequence ``\\\^\fIspace\fP'' (backslash followed by space) +is recognized and replaced by a space character, +and the two-character sequence ``\\\^\fItab\fP'' +(backslash followed by horizontal tab) +is recognized and replaced by a horizontal tab character. +To allow a Value to contain embedded newline characters, +the two-character sequence ``\\\^n'' is recognized and replaced by a +newline character. +To allow a Value to be broken across multiple lines in a text file, +the two-character sequence ``\\\^\fInewline\fP'' +(backslash followed by newline) is +recognized and removed from the value. +To allow a Value to contain arbitrary character codes, +the four-character sequence ``\\\^\fInnn\fP'', +where each \fIn\fP is a digit character in the range of ``0''\-``7'', +is recognized and replaced with a single byte that contains +the octal value specified by the sequence. +Finally, the two-character sequence ``\\\\'' is recognized +and replaced with a single backslash. +.PP +When an application looks for the value of a resource, it specifies +a complete path in the hierarchy, with both class and instance names. +However, resource values are usually given with only partially specified +names and classes, using pattern matching constructs. +An asterisk (*) is a loose binding and is used to represent any number +of intervening components, including none. +A period (.) is a tight binding and is used to separate immediately +adjacent components. +A question mark (?) is used to match any single component name or class. +A database entry cannot end in a loose binding; +the final component (which cannot be "?") must be specified. +The lookup algorithm searches the resource database for the entry that most +closely matches (is most specific for) the full name and class being queried. +When more than one database entry matches the full name and class, +precedence rules are used to select just one. +.LP +The full name and class are scanned from left to right (from highest +level in the hierarchy to lowest), one component at a time. +At each level, the corresponding component and/or binding of each +matching entry is determined, and these matching components and +bindings are compared according to precedence rules. +Each of the rules is applied at each level, +before moving to the next level, +until a rule selects a single entry over all others. +The rules (in order of precedence) are: +.IP 1. 5 +An entry that contains a matching component (whether name, class, or "?") +takes precedence over entries that elide the level (that is, entries +that match the level in a loose binding). +.IP 2. 5 +An entry with a matching name takes precedence over both +entries with a matching class and entries that match using "?". +An entry with a matching class takes precedence over +entries that match using "?". +.IP 3. 5 +An entry preceded by a tight binding takes precedence over entries +preceded by a loose binding. +.PP +Programs based on the X Tookit Intrinsics +obtain resources from the following sources +(other programs usually support some subset of these sources): +.TP 8 +.B "RESOURCE_MANAGER root window property" +Any global resources that should be available to clients on all machines +should be stored in the RESOURCE_MANAGER property on the +root window of the first screen using the \fIxrdb\fP program. +This is frequently taken care +of when the user starts up X through the display manager or \fIxinit\fP. +.TP 8 +.B "SCREEN_RESOURCES root window property" +Any resources specific to a given screen (e.g. colors) +that should be available to clients on all machines +should be stored in the SCREEN_RESOURCES property on the +root window of that screen. +The \fIxrdb\fP program will sort resources automatically and place them +in RESOURCE_MANAGER or SCREEN_RESOURCES, as appropriate. +.TP 8 +.B "application-specific files" +Directories named by the environment variable XUSERFILESEARCHPATH +or the environment variable XAPPLRESDIR (which names a single +directory and should end with a '/' on POSIX systems), plus directories in a +standard place (usually under __projectroot__/lib/X11/, +but this can be overridden with the XFILESEARCHPATH environment variable) +are searched for for application-specific resources. +For example, application default resources are usually kept in +__projectroot__/lib/X11/app-defaults/. +See the \fIX Toolkit Intrinsics - C Language Interface\fP manual for +details. +.TP 8 +.B XENVIRONMENT +Any user- and machine-specific resources may be specified by setting +the XENVIRONMENT environment variable to the name of a resource file +to be loaded by all applications. If this variable is not defined, +a file named \fI$HOME\fP/.Xdefaults-\fIhostname\fP is looked for instead, +where \fIhostname\fP is the name of the host where the application +is executing. +.TP 8 +.B \-xrm \fIresourcestring\fP +Resources can also be specified from the +command line. The \fIresourcestring\fP is a single resource name and value as +shown above. Note that if the string contains characters interpreted by +the shell (e.g., asterisk), they must be quoted. +Any number of \fB\-xrm\fP arguments may be given on the +command line. +.PP +Program resources are organized into groups called \fIclasses\fP, so that +collections of individual resources (each of which are +called \fIinstances\fP) +can be set all at once. By convention, the instance name of a resource +begins with a lowercase letter and class name with an upper case letter. +Multiple word resources are concatenated with the first letter of the +succeeding words capitalized. Applications written with the X Toolkit +Intrinsics will have at least the following resources: +.PP +.TP 8 +.B background (\fPclass\fB Background) +This resource specifies the color to use for the window background. +.PP +.TP 8 +.B borderWidth (\fPclass\fB BorderWidth) +This resource specifies the width in pixels of the window border. +.PP +.TP 8 +.B borderColor (\fPclass\fB BorderColor) +This resource specifies the color to use for the window border. +.PP +Most applications using the X Toolkit Intrinsics also have the resource +\fBforeground\fP +(class \fBForeground\fP), specifying the color to use for text +and graphics within the window. +.PP +By combining class and instance specifications, application preferences +can be set quickly and easily. Users of color displays will frequently +want to set Background and Foreground classes to particular defaults. +Specific color instances such as text cursors can then be overridden +without having to define all of the related resources. For example, +.sp +.nf + bitmap*Dashed: off + XTerm*cursorColor: gold + XTerm*multiScroll: on + XTerm*jumpScroll: on + XTerm*reverseWrap: on + XTerm*curses: on + XTerm*Font: 6x10 + XTerm*scrollBar: on + XTerm*scrollbar*thickness: 5 + XTerm*multiClickTime: 500 + XTerm*charClass: 33:48,37:48,45-47:48,64:48 + XTerm*cutNewline: off + XTerm*cutToBeginningOfLine: off + XTerm*titeInhibit: on + XTerm*ttyModes: intr ^c erase ^? kill ^u + XLoad*Background: gold + XLoad*Foreground: red + XLoad*highlight: black + XLoad*borderWidth: 0 + emacs*Geometry: 80x65-0-0 + emacs*Background: rgb:5b/76/86 + emacs*Foreground: white + emacs*Cursor: white + emacs*BorderColor: white + emacs*Font: 6x10 + xmag*geometry: -0-0 + xmag*borderColor: white +.fi +.PP +If these resources were stored in a file called \fI.Xresources\fP in your home +directory, they could be added to any existing resources in the server with +the following command: +.sp +.nf + % xrdb -merge $HOME/.Xresources +.fi +.sp +This is frequently how user-friendly startup scripts merge user-specific +defaults +into any site-wide defaults. All sites are encouraged to set up convenient +ways of automatically loading resources. See the \fIXlib\fP +manual section \fIResource Manager Functions\fP for more information. +.SH ENVIRONMENT +.TP +.SM +.B DISPLAY +This is the only mandatory environment variable. It must point to an +X server. See section "Display Names" above. +.TP +.SM +.B XAUTHORITY +This must point to a file that contains authorization data. The default +is \fI$HOME/.Xauthority\fP. See +.BR Xsecurity (__miscmansuffix__), +.BR xauth (1), +.BR xdm (1), +.BR Xau (3). +.TP +.SM +.B ICEAUTHORITY +This must point to a file that contains authorization data. The default +is \fI$HOME/.ICEauthority\fP. +.TP +.SM +.BR LC_ALL ", " LC_CTYPE ", " LANG +The first non-empty value among these three determines the current +locale's facet for character handling, and in particular the default +text encoding. See +.BR locale (__miscmansuffix__), +.BR setlocale (3), +.BR locale (1). +.TP +.SM +.B XMODIFIERS +This variable can be set to contain additional information important +for the current locale setting. Typically set to \fI@im=<input-method>\fP +to enable a particular input method. See +.BR XSetLocaleModifiers (3). +.TP +.SM +.B XLOCALEDIR +This must point to a directory containing the locale.alias file and +Compose and XLC_LOCALE file hierarchies for all locales. The default value +is\fI __projectroot__/lib/X11/locale\fP. +.TP +.SM +.B XENVIRONMENT +This must point to a file containing X resources. The default is +\fI$HOME/.Xdefaults-<hostname>\fP. Unlike\fI __projectroot__/lib/X11/Xresources\fP, +it is consulted each time an X application starts. +.TP +.SM +.B XFILESEARCHPATH +This must contain a colon separated list of path templates, where libXt +will search for resource files. The default value consists of +.sp +.nf + __projectroot__/lib/X11/%L/%T/%N%C%S:\\ + __projectroot__/lib/X11/%l/%T/%N%C%S:\\ + __projectroot__/lib/X11/%T/%N%C%S:\\ + __projectroot__/lib/X11/%L/%T/%N%S:\\ + __projectroot__/lib/X11/%l/%T/%N%S:\\ + __projectroot__/lib/X11/%T/%N%S +.fi +.sp +A path template is transformed to a pathname by substituting: +.sp +.nf + %N => name (basename) being searched for + %T => type (dirname) being searched for + %S => suffix being searched for + %C => value of the resource "customization" + (class "Customization") + %L => the locale name + %l => the locale's language (part before '_') + %t => the locale's territory (part after '_` but before '.') + %c => the locale's encoding (part after '.') +.fi +.TP +.SM +.B XUSERFILESEARCHPATH +This must contain a colon separated list of path templates, +where libXt will search for user dependent resource files. The default +value is: +.sp +.nf + $XAPPLRESDIR/%L/%N%C:\\ + $XAPPLRESDIR/%l/%N%C:\\ + $XAPPLRESDIR/%N%C:\\ + $HOME/%N%C:\\ + $XAPPLRESDIR/%L/%N:\\ + $XAPPLRESDIR/%l/%N:\\ + $XAPPLRESDIR/%N:\\ + $HOME/%N +.fi +.sp +$XAPPLRESDIR defaults to \fI$HOME\fP, see below. +.sp +A path template is transformed to a pathname by substituting: +.sp +.nf + %N => name (basename) being searched for + %T => type (dirname) being searched for + %S => suffix being searched for + %C => value of the resource "customization" + (class "Customization") + %L => the locale name + %l => the locale's language (part before '_') + %t => the locale's territory (part after '_` but before '.') + %c => the locale's encoding (part after '.') +.fi +.TP +.SM +.B XAPPLRESDIR +This must point to a base directory where the user stores his application +dependent resource files. The default value is \fI$HOME\fP. Only used if +XUSERFILESEARCHPATH is not set. +.TP +.SM +.B XKEYSYMDB +This must point to a file containing nonstandard keysym definitions. +The default value is\fI __projectroot__/lib/X11/XKeysymDB\fP. +.TP +.SM +.B XCMSDB +This must point to a color name database file. The default value is +\fI\__projectroot__/lib/X11/Xcms.txt\fP. +.TP +.SM +.B XFT_CONFIG +This must point to a configuration file for the Xft library. The default +value is\fI __projectroot__/lib/X11/XftConfig\fP. +.TP +.SM +.B RESOURCE_NAME +This serves as main identifier for resources belonging to the program +being executed. It defaults to the basename of pathname of the program. +.TP +.SM +.B SESSION_MANAGER +Denotes the session manager the application should connect. See +.BR xsm (1), +.BR rstart (1). +.TP +.SM +.B XF86BIGFONT_DISABLE +Setting this variable to a non-empty value disables the XFree86-Bigfont +extension. This extension is a mechanism to reduce the memory consumption +of big fonts by use of shared memory. +.LP +.B XKB_FORCE +.br +.B XKB_DISABLE +.br +.B XKB_DEBUG +.br +.B _XKB_CHARSET +.br +.B _XKB_LOCALE_CHARSETS +.br +.B _XKB_OPTIONS_ENABLE +.br +.B _XKB_LATIN1_LOOKUP +.br +.B _XKB_CONSUME_LOOKUP_MODS +.br +.B _XKB_CONSUME_SHIFT_AND_LOCK +.br +.B _XKB_IGNORE_NEW_KEYBOARDS +.br +.B _XKB_CONTROL_FALLBACK +.br +.B _XKB_COMP_LED +.B _XKB_COMP_FAIL_BEEP +.TP +.SM +.I "" +These variables influence the X Keyboard Extension. +.SH EXAMPLES +The following is a collection of sample command lines for some of the +more frequently used commands. For more information on a particular command, +please refer to that command's manual page. +.sp +.nf + % xrdb $HOME/.Xresources + % xmodmap -e "keysym BackSpace = Delete" + % mkfontdir /usr/local/lib/X11/otherfonts + % xset fp+ /usr/local/lib/X11/otherfonts + % xmodmap $HOME/.keymap.km + % xsetroot -solid 'rgbi:.8/.8/.8' + % xset b 100 400 c 50 s 1800 r on + % xset q + % twm + % xmag + % xclock -geometry 48x48-0+0 -bg blue -fg white + % xeyes -geometry 48x48-48+0 + % xbiff -update 20 + % xlsfonts '*helvetica*' + % xwininfo -root + % xdpyinfo -display joesworkstation:0 + % xhost -joesworkstation + % xrefresh + % xwd | xwud + % bitmap companylogo.bm 32x32 + % xcalc -bg blue -fg magenta + % xterm -geometry 80x66-0-0 -name myxterm $* + % xon filesysmachine xload +.fi +.SH DIAGNOSTICS +A wide variety of error messages are generated from various programs. +The default error handler in \fIXlib\fP (also used by many toolkits) uses +standard resources to construct diagnostic messages when errors occur. The +defaults for these messages are usually stored in +\fI\__projectroot__/lib/X11/XErrorDB\fP. If this file is not present, +error messages will be rather terse and cryptic. +.PP +When the X Toolkit Intrinsics encounter errors converting resource strings to +the +appropriate internal format, no error messages are usually printed. This is +convenient when it is desirable to have one set of resources across a variety +of displays (e.g. color vs. monochrome, lots of fonts vs. very few, etc.), +although it can pose problems for trying to determine why an application might +be failing. This behavior can be overridden by the setting the +\fIStringConversionsWarning\fP resource. +.PP +To force the X Toolkit Intrinsics to always print string conversion error +messages, +the following resource should be placed in the file that gets +loaded onto the RESOURCE_MANAGER property +using the \fIxrdb\fP program (frequently called \fI.Xresources\fP +or \fI.Xres\fP in the user's home directory): +.sp +.nf + *StringConversionWarnings: on +.fi +.sp +To have conversion messages printed for just a particular application, +the appropriate instance name can be placed before the asterisk: +.sp +.nf + xterm*StringConversionWarnings: on +.fi +.SH "SEE ALSO" +.PP +.\" introductions +.BR XOrgFoundation (__miscmansuffix__), +.BR XStandards (__miscmansuffix__), +.BR Xsecurity (__miscmansuffix__), +.BR Xprint (__miscmansuffix__), +.\" clients, utilities, and demos +.BR appres (1), +.BR bdftopcf (1), +.BR bitmap (1), +.BR editres (1), +.BR fsinfo (1), +.BR fslsfonts (1), +.BR fstobdf (1), +.BR iceauth (1), +.BR imake (1), +.BR lbxproxy (1), +.BR kbd_mode (1), +.BR makedepend (1), +.BR mkfontdir (1), +.BR oclock (1), +.BR proxymngr (1), +.BR rgb (1), +.BR resize (1), +.BR rstart (1), +.BR smproxy (1), +.BR twm (1), +.BR x11perf (1), +.BR x11perfcomp (1), +.BR xauth (1), +.BR xclipboard (1), +.BR xclock (1), +.BR xcmsdb (1), +.BR xconsole (1), +.BR xdm (1), +.BR xdpyinfo (1), +.BR xfd (1), +.BR xfindproxy (1), +.BR xfs (1), +.BR xfwp (1), +.BR xhost (1), +.BR xinit (1), +.BR xkbbell (1), +.BR xkbcomp (1), +.BR xkbevd (1), +.BR xkbprint (1), +.BR xkbvleds (1), +.BR xkbwatch (1), +.BR xkill (1), +.BR xlogo (1), +.BR xlsatoms (1), +.BR xlsclients (1), +.BR xlsfonts (1), +.BR xmag (1), +.BR xmh (1), +.BR xmodmap (1), +.BR xon (1), +.BR xplsprinters (1), +.BR xprop (1), +.BR xrdb (1), +.BR xrefresh (1), +.BR xrx (1), +.BR xset (1), +.BR xsetroot (1), +.BR xsm (1), +.BR xstdcmap (1), +.BR xterm (1), +.BR xwd (1), +.BR xwininfo (1), +.BR xwud (1). +.\" servers +.BR Xserver (1), +.BR Xdec (1), +.BR Xdmx (1), +.BR XmacII (1), +.BR Xsun (1), +.BR Xnest (1), +.BR Xvfb (1), +.BR Xorg (1), +.BR XDarwin (1), +.BR Xprt (1). +.\" specifications +.I "Xlib \- C Language X Interface\fR,\fP" +and +.I "X Toolkit Intrinsics \- C Language Interface" +.SH TRADEMARKS +.PP +X Window System is a trademark of The Open Group. +.SH AUTHORS +.PP +A cast of thousands, literally. Releases 6.7 and later are +brought to you by the X.Org Foundation, LLC. The names of all people who +made it a reality will be found in the individual documents and +source files. +.PP +Releases 6.6 and 6.5 were done by The X.Org Group. Release 6.4 was done by +The X Project Team. The Release 6.3 distribution was from The X Consortium, +Inc. The staff members at the X Consortium responsible for that release +were: Donna Converse (emeritus), Stephen Gildea (emeritus), Kaleb Keithley, +Matt Landau (emeritus), Ralph Mor (emeritus), Janet O'Halloran, Bob +Scheifler, Ralph Swick, Dave Wiggins (emeritus), and Reed Augliere. +.PP +The X Window System standard was originally developed at the +Laboratory for Computer Science at the Massachusetts Institute +of Technology, and all rights thereto were assigned to the X Consortium +on January 1, 1994. +X Consortium, Inc. closed its doors on December 31, 1996. All rights to the +X Window System have been assigned to The Open Group. diff --git a/doc/xorg-docs/man/general/XOrgFoundation.man b/doc/xorg-docs/man/general/XOrgFoundation.man new file mode 100644 index 000000000..4d9946d82 --- /dev/null +++ b/doc/xorg-docs/man/general/XOrgFoundation.man @@ -0,0 +1,56 @@ +.\" +.\" Copyright 2004, 2005 X.Org Foundation, LLC +.\" Copyright (c) 1993, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the "Software"), +.\" to deal in the Software without restriction, including without limitation +.\" the rights to use, copy, modify, merge, publish, distribute, sublicense, +.\" and/or sell copies of the Software, and to permit persons to whom the +.\" Software furnished to do so, subject to the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included in +.\" all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +.\" THE X.ORG FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +.\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF +.\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +.\" SOFTWARE. +.\" +.TH XORGFOUNDATION __miscmansuffix__ __xorgversion__ +.SH NAME +XOrgFoundation \- X.Org Foundation information +.SH SYNOPSIS +Release 7.0 of X Version 11 is brought to you by the X.Org Foundation, LLC. +.SH DESCRIPTION +The X.Org Foundation is an independent, not-for-profit 501(c)(3) charity +corporation. It was formed in 2004 as the successor to the X.Org Group at +The Open Group. The purpose of the X.Org Foundation is to foster the +development, evolution, and maintenance of the X Window System, a +comprehensive set of vendor-neutral, system-architecture neutral, +network-transparent windowing and user interface standards. Membership +in the X.Org Foundation is free and open to anyone. The X.Org Foundation +hosts a public CVS repository of the source code on Freedesktop.Org. +.PP +The X Window System was created in the mid-1980s at the Massachusetts +Institute of Technology. In 1988, MIT formed a member-funded consortium to +provide the technical and administrative leadership necessary to support +further development of the X Window System. In 1992, MIT and the membership +decided it was in their best interests to move the consortium out of MIT and +create an independent, stand-alone organization. All rights to the X Window +System were assigned by MIT to X Consortium, Inc. on January 1, 1994. On +December 31, 1996 the X Consortium, Inc. closed its doors and all rights +to the X Window System were assigned to The Open Group (then known as the +Open Software Foundation.) +.PP +.SH "ADDRESSES" +The X.Org Foundation's web site is http://www.x.org/ +.PP +The X.Org Foundation's public ftp site is ftp://ftp.x.org/ +.PP +Information about the X.Org Foundation CVS repository is on the +Freedesktop.Org web site at http://www.freedesktop.org/Software/xorg +.fi diff --git a/doc/xorg-docs/man/general/XProjectTeam.man b/doc/xorg-docs/man/general/XProjectTeam.man new file mode 100644 index 000000000..d7673dad5 --- /dev/null +++ b/doc/xorg-docs/man/general/XProjectTeam.man @@ -0,0 +1,91 @@ +.\" $Xorg: XProjectTeam.cpp,v 1.6 2001/01/29 17:44:41 coskrey Exp $ +.\" Copyright (c) 1993, 1994, 1996 X Consortium +.\" Copyright (c) 1996, 2000 The Open Group +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the "Software"), +.\" to deal in the Software without restriction, including without limitation +.\" the rights to use, copy, modify, merge, publish, distribute, sublicense, +.\" and/or sell copies of the Software, and to permit persons to whom the +.\" Software furnished to do so, subject to the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included in +.\" all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +.\" THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +.\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF +.\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +.\" SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall not +.\" be used in advertising or otherwise to promote the sale, use or other +.\" dealing in this Software without prior written authorization from the +.\" X Consortium. +.\" +.\" $XFree86: xc/doc/man/general/XProjectTeam.man,v 1.2 2001/01/27 18:20:38 dawes Exp $ +.\" +.TH XORG __miscmansuffix__ __xorgversion__ +.SH NAME +X.Org, XProjectTeam \- X.Org Group information +.SH SYNOPSIS +Release 6.5 and 6.6 of X Version 11 was brought to you by The X.Org Group. +Release 6.4 of X Version 11 was brought to you by The X Project Team. +.SH DESCRIPTION +The Open Group's X Project Team was created as the successor +to the X Consortium, Inc., after the X Consortium ceased operations and +transferred ownership of X11 to The Open Group. The X.Org Group +(hereinafter called "X.Org") was created as the successor to The X Project +Team after the The Open Group ceased operating The X Project Team. The +purpose of X.Org was to foster development, evolution, and maintenance of +the X Window System. X.Org operates under the corporate umbrella of The +Open Group. +.PP +The X Consortium was an independent, not-for-profit Delaware membership +corporation. It was formed in 1993 as the successor to the MIT X +Consortium. +.PP +The X Window System was created in the mid-1980s at the Massachusetts +Institute of Technology. In 1988, MIT formed a member-funded consortium +to provide the technical and administrative leadership necessary to +support further development of the X Window System. In 1992, MIT and +the membership decided it was in their best interests to move the +consortium out of MIT and create an independent, stand-alone organization. +All rights to the X Window System were assigned by MIT to X Consortium, +Inc. on January 1, 1994. On December 31, 1996 the X Consortium, Inc. +closed its doors and all rights to the X Window System were assigned to +The Open Group. +.PP +.SH "ADDRESS" +To reach The Open Group public World Wide Web server, use +http://www.opengroup.org/. +.PP +To reach The X.Org public World Wide Web server, use +http://www.x.org/. +.PP +To reach The X.Org public ftp machine, use anonymous ftp at +ftp://ftp.x.org/ + +.SH "FULL MEMBERS" + +.nf +Attachmate +Barco +Compaq +Hewlett-Packard +Hummingbird +IBM +ICS +Metro Link +MITRE +Shiman Associates +Silicon Graphics Incorporated +Starnet Communications +Sun Microsystems +The XFree86 Project +US Navy +WRQ +Xi Graphics +.fi diff --git a/doc/xorg-docs/man/general/Xprint.man b/doc/xorg-docs/man/general/Xprint.man new file mode 100644 index 000000000..39b0ccc70 --- /dev/null +++ b/doc/xorg-docs/man/general/Xprint.man @@ -0,0 +1,421 @@ +.\" -*- coding: us-ascii -*- +.TH Xprint __miscmansuffix__ "8 October 2004" +.SH NAME +Xprint \- The "X print service" - a portable, network-transparent printing system based on the X11 protocol +.SH SYNOPSIS +Xprint is a very flexible, extensible, scaleable, client/server +print system based on ISO 10175 (and some other specs) and the X11 +rendering protocol. +Using Xprint an application can search, query and use devices like +printers, FAX machines or create documents in formats like PDF. +In particular, an application can seek a printer, query supported +attributes (like paper size, trays, fonts etc.), configure the printer +device to match it\(cqs needs and print on it like on any other X device +reusing parts of the code which is used for the video card Xserver. +.SH OVERVIEW +The "X Print Service" technology allows X rendering to devices such as +printers and fax. Most of the service is available in the X11 +technology stack as Xp, with the remainder in single toolkit stacks (e.g. DtPrint for CDE). +Modifications have also been made to the LessTif/Motif/Qt technology +stacks to support Xprint. +.PP +The Xp portion consists of: +.TP 0.2i +\(bu +Xp Extension for the X-Server (included in the X-Server Xprt) +.TP 0.2i +\(bu +Xp Extension API for the client side (libXp/libXprintUtils) +.TP 0.2i +\(bu +PCL ddx driver that converts core X to native PCL +.TP 0.2i +\(bu +PDF ddx driver that converts core X to native PDF +.TP 0.2i +\(bu +PostScript ddx driver that converts core X to native PostScript +.TP 0.2i +\(bu +Raster ddx driver that generates xwd rasters which can be converted to PCL, PDF or PostScript rasters +.PP +.PP +From an X clients perspective, it can attach to one of two nearly +identical X-Servers, a "Video" X-Server, and a "Print" X-Server +which has the additional Xp capability but otherwise looks and +behaves the same. +.SH "HOW THE X PRINT SERVICE WORKS" +The X Print Service expands on the traditional X-Server and Xlib world +in four ways. +.TP 0.4i +1. +Most obvious is the use of "print ddx drivers" instead of +"video ddx drivers". While a video ddx driver modifies pixels +in a video frame buffer, a print ddx driver generates "page +description language (PDL)" output (such as PCL, PDF or PostScript) +or sends the print rendering instructions to a platform-specific +print API (like Win32/GDI). + +Once a print ddx driver generates PDL output, it can be sent to +a spooler such as \fBlp\fR(1) +or retrieved by the client (to implement functionality like "print-to-file"). + +Though not currently done, a single X-Server can support both +print and video ddx drivers. +.TP 0.4i +2. +Since printers support "paged" output, unlike video, a portion +of the Xp Extension supports APIs to delineate printed output. +For example, XpStartPage and XpEndPage tell the X-Server where +a physical page starts and ends in an otherwise continuous +stream of X rendering primitives. Likewise, XpStartJob and +XpEndJob determine when a collection of pages starts and ends. +XpEndJob typically causes the generated PDL to be submitted to +a spooler, such as \fBlp\fR(1). +.TP 0.4i +3. +Since printers have extensive capabilities, another portion of +the Xp Extension supports APIs to manipulate "print contexts". + +Once a printer is selected using the Xp Extension API, a print +context to represent it can be created. A print context +embodies the printer selected - it contains the printer's +default capabilities, selectable range of capabilities, +printer state, and generated output. Some "attributes" within +the print context can be modified by the user, and the +X-Server and print ddx driver will react accordingly. For +example, the attribute "content-orientation" can be set to +"landscape" or "portrait" (if the printer supports these +values - which can be queried using the Xprint API as well). +.TP 0.4i +4. +Since printers can have "built in" fonts, the Xp Extension in +the X-Server works with the print ddx drivers to make +available (for printing only) additional fonts on a per print +context basis. + +When a print context is created and set for a given printer, +the X font calls may be able to access additional printer +fonts. To do this (typically), the X-Server must have access +to "printer metric files" (.pmf) that describe at minimum the +metrics of the built in fonts. +.PP +.SH USAGE +There are three tasks to start the X Print Service: +.TP 0.4i +1. +configuring the X Print Server, +.TP 0.4i +2. +starting the X Print Service +.TP 0.4i +3. +configuring the user session so that clients can find the running X Print Service +.PP +.PP +The tasks are described in detail below. +.SH "SERVER CONFIGURATION" +The X Print Server (Xprt) can read a number of configuration files which +control its behavior and support for printers. Each vendor platform has +a default location for this information. Xprt can also read the +environment variable \fBXPCONFIGDIR\fR to locate alternate configuration +directories. Common settings include: + +export XPCONFIGDIR=/X11/lib/X11/XpConfig/ +.PP +export XPCONFIGDIR=/proj/x11/xc/programs/Xserver/XpConfig/ + +.PP +Xprt has many built-in defaults, and lacking any configuration files, +will immediately try to support all printers visible via \fBlpstat\fR(1). +.PP +In order of importance for configuration by a system administrator, the +configuration files for a "C" locale are as follows (see \fBXprt\fR(__appmansuffix__) for more +details (including support for non-"C" locales)): +.TP +\fB${XPCONFIGDIR}/C/print/Xprinters\fR +\&'Xprinters' is the top most configuration file. It tells +Xprt which specific printer names (e.g. mylaser) should +be supported, and whether \fBlpstat\fR(1) or other commands +should be used to automatically supplement the list of +printers. +.TP +\fB${XPCONFIGDIR}/C/print/attributes/printer\fR +The 'printer' file maps printer names to model +configurations (see 'model-config' below). For example, +"mylaser" could be mapped to a "HPDJ1600C", and all other +arbitrary printers could be mapped to a default, such as +"HPLJ4SI". When depending on \fBlpstat\fR(1) in the Xprinters +file, setting up defaults in 'printer' becomes all the +more important. +.TP +\fB${XPCONFIGDIR}/C/print/attributes/document\fR +The 'document' file specifies the initial document values +for any print jobs. For example, which paper tray to +use, what default resolution, etc. +.TP +\fB${XPCONFIGDIR}/C/print/attributes/job\fR +The 'job' file specifies the initial job values for any +print jobs. For example, "notification-profile" can be +set so that when a print job is successfully sent to a +printer, e-mail is sent to the user. +.TP +\fB${XPCONFIGDIR}/C/print/models/PSdefault/model\-config\fR, \fB${XPCONFIGDIR}/C/print/models/PSdefault/fonts/fonts.dir\fR, \fB${XPCONFIGDIR}/C/print/models/PSdefault/fonts/9nb00051.pmf\fR, \fB${XPCONFIGDIR}/C/print/models/PSdefault/fonts/9nb00093.pmf\fR +The 'model-config' file has attributes that describe the +printer model\(cqs capabilities and default settings. +Printer model fonts may also be present. The model-config +file also identifies the print ddx driver to be used. +For each printer model supported, a complete hierarchy of +files should exist. In most cases, these files do not +need to be modified. +.TP +\fB${XPCONFIGDIR}/C/print/ddx\-config/raster/pcl\fR, \fB${XPCONFIGDIR}/C/print/ddx\-config/raster/pdf\fR, \fB${XPCONFIGDIR}/C/print/ddx\-config/raster/postscript\fR +The print ddx drivers can have highly specific +configuration files to control their behavior. In most +cases, these files do not need to be modified. +.PP +More information in how to configure and customize the X print server can be found in the +\fBXprt\fR(__appmansuffix__) +manual page. +.SH "STARTING UP" +The summary checklist for starting the X Print Service is as follows: +.TP 0.4i +1. +Choose an execution model for the X Print Service. The X +Print Service can be run on a per-user session basis, per +machine basis, or can be run on a few machines globally +available to a number of users. +.TP 0.4i +2. +If print jobs are to be submitted to a spooler (almost always +the case), make sure all needed printers are available to the +spooler subsystem (most often \fBlp\fR(1)) +on the same machine running the X Print Service. +.TP 0.4i +3. +Configure the X Print Server. See ``X Print Server +Configuration''. +.TP 0.4i +4. +Depending on #1, start the X Print Server process "Xprt", and +then the toolkit-specific Print Dialog Manager Daemon process +(such as CDEnext's "dtpdmd") at the appropriate times. +Note that libXprintUtils-based applications/toolkits do not need +a Print Dialog Manager Daemon process to use Xprint. +.PP +The details are described below. +.PP +Because the X Print Service is based on X, it can be easily distributed. +The most significant factors in which execution model to choose will be +driven by: +.TP 0.2i +\(bu +how many printers will be accessable through the printer +subsystem on any given machine. A system administrator may +choose to cluster printers on a few given machines, or +scatter them across an organization and possibly make +extensive use of remote spoolers to make them globally +available. +.TP 0.2i +\(bu +how many machines will need a copy of the X Print Server +configuration files. The files have been architected so +that one super-set version of them can be maintained and +distributed (e.g. via NFS), and a per-machine or per-user +version of the `Xprinters' is all that is needed to have the +appropriate information in them utilized or ignored. +.TP 0.2i +\(bu +how many users can demand services from a given X Print +Service. +.PP +With the above in mind, some obvious execution models include: +.TP 0.2i +\(bu +Global - in this model, the system administrator is choosing +to run the X Print Service on a *few* select machines with +appropriate printers configured, and allow clients access to +the global resource. This can centralize the administration +of printers and configuration files, but may have to be +monitored for performance loading. + +Startup would likely be done by boot-up scripts (such as \fB/etc/init.d/xprint\fR). +.TP 0.2i +\(bu +Per-machine - every machine with potential X Print Service +users would run the service. Printer and configuration file +administration is decentralized, and usage would be limited +to the users on the machine. + +Startup would likely be done by boot-up scripts (such as \fB/etc/init.d/xprint\fR). +.TP 0.2i +\(bu +Per-user session - every user would run an entire X Print +Service for themselves. In the future, the Video X Server +normally started may contain Print X Server capability, so +this model becomes very natural. + +Startup would likely be done at session login or by +launching actions or processes manually once the user +logs in. Note: Deamons like "dtpdmd" must be started after Xprt. +.PP +.PP +Starting of the processes is straight forward. In strict order (example is for manually starting the X print server for CDEnext usage): +.TP 0.4i +1. + +.nf +[machineA] % Xprt [\-XpFile <Xprinters file>] [:dispNum] & +.fi + + +Note that Xprt will look for configuration files in either +a default location or where \fBXPCONFIGDIR\fR points. + +\fB\-XpFile\fR specifies an alternate `Xprinters' file, rather +than the default one or `\fB${XPCONFIGDIR}/C/print/Xprinters\fR'. +.TP 0.4i +2. + +.nf +[machineA] % dtpdmd \-d machineA[:dispNum] [\-l /tmp/dtpdmd.log] & +.fi + + +The dtpdmd will maintain an X-Selection on the X-Server, +and will start dtpdm's as required to service requests. +.PP +.PP +In all but the per-user session model, the machine running the dtpdmd +(thus dtpdm's) will need display authorization to the users video +display. +.SH "CLIENT CONFIGURATION" +Once a X Print Server and dtpdmd have been started -- many of them +in some cases -- clients will need to find and use them. There are +two mechanisms that allow clients to discover X Print Servers and +printers. +.TP 0.2i +\(bu +"X Print Specifier" - assuming usage of the DtPrint/XprintUtils-based print +applications, the following notation is understood: + + +.nf +printer_name@machine[:dispNum] +.fi + + +For example: + + +.nf +colorlj7@printhub:2 +.fi + + +In the above example, the X Print Server running at `printhub:2' +is assumed to support the printer named `colorlj7'. +.TP 0.2i +\(bu +\fB${XPSERVERLIST}\fR - assuming usage of the DtPrint print dialogs, +the environment variable \fB${XPSERVERLIST}\fR can contain a list +of X Print Servers. For example: + + +.nf +XPSERVERLIST="printhub:2 printhub:3 otherdept:0" +.fi + + +Then in the dialogs, only a printer name needs to be entered. +The dialog will then search the X Print Servers in \fB${XPSERVERLIST}\fR +for a server than supports the printer, and then establish +contact. +.PP +.SH "END-USER SEQUENCE" +From most CDEnext applications, printing is accomplished by bringing +down the <File> menu and selecting <Print...>. This will result in +the DtPrintSetupBox dialog, which will request the name of a printer, +and offer limited capability to configure print options (e.g. number +of copies). If the user wishes, they can select <Setup...>, which +will start a dtpdm capable of modifying additional print options. +Finally, the user should select <Print>. +.SH ENVIRONMENT +.TP +\fB${XPCONFIGDIR}\fR +This environment variable points to the root +of the Xprint server configuration directory hierarchy. +If the variable is not defined, the default +path is be assumed. The default path may be +\fB/usr/X11R6/lib/X11/xserver/\fR, +\fB/usr/lib/X11/xserver/\fR, +\fB/usr/share/Xprint/xserver/\fR or +\fB/usr/openwin/server/etc/XpConfig\fR, depending on the +system, and may be configured in \fB/etc/init.d/xprint\fR. +.TP +\fB${LANG}\fR +This environment variable selects the locale settings used by the Xprint server. +Xprt allows language-specific settings (stored in \fB${XPCONFIGDIR}/${LANG}/print/\fR) +which will override the default settings (stored in \fB${XPCONFIGDIR}/C/print/\fR). +If \fB${LANG}\fR is not set "C" is assumed. +.TP +\fB${XPSERVERLIST}\fR +The environment variable \fB${XPSERVERLIST}\fR contains a list +of display identifiers (separated by whitespace) which tell an +application where it can find the Xprint servers. Usually +\fB${XPSERVERLIST}\fR is set by the profile startup scripts (e.g. +\fB/etc/profile\fR or \fB/etc/profile.d/xprint.sh\fR) using the output of +\fB/etc/init.d/xprint get_xpserverlist\fR. + +Example: + +.nf + + export XPSERVERLIST="`/etc/init.d/xprint get_xpserverlist`" +.fi + + +Alternatively \fB${XPSERVERLIST}\fR can be set +manually. Example: + +.nf + + export XPSERVERLIST="littlecat:80 bitdog:72" +.fi + +instructs an application to find an Xprint server at display +80 on the machine "littlecat" and at display 72 on the +machine bigdog. +.TP +\fB${XPRINTER}\fR +The environment variable \fB${XPRINTER}\fR +defines the default printer used by print +applications. The syntax is either +\fIprintername\fR or +\fIprintername\fR@\fIdisplay\fR. + +Examples: +.RS +.TP +\fBXPRINTER=ps003\fR +tells an application to look for the +first printer named "ps003" on all Xprint +servers. +.TP +\fBXPRINTER=hplaser19@littlecat:80\fR +tells an application to use the printer "hplaser19" +on the Xprint server at display +"littlecat:80". +.RE + + +If \fB${XPRINTER}\fR is not set the applications +will examine the values of the \fB${PDPRINTER}\fR, +\fB${LPDEST}\fR, and +\fB${PRINTER}\fR environment variables (in that order). +.SH "SEE ALSO" +\fBX11\fR(__miscmansuffix__), \fBxplsprinters\fR(__appmansuffix__), \fBxprehashprinterlist\fR(__appmansuffix__), \fBxphelloworld\fR(__appmansuffix__), \fBxpxmhelloworld\fR(__appmansuffix__), \fBxpawhelloworld\fR(__appmansuffix__), \fBxpxthelloworld\fR(__appmansuffix__), \fBxpsimplehelloworld\fR(__appmansuffix__), \fBXserver\fR(__appmansuffix__), \fBXprt\fR(__appmansuffix__), \fBlibXp\fR(__libmansuffix__), \fBlibXprintUtils\fR(__libmansuffix__), \fBlibXprintAppUtils\fR(__libmansuffix__), \fBXmPrintShell\fR(__libmansuffix__), \fBXawPrintShell\fR(__libmansuffix__), Xprint FAQ (http://xprint.mozdev.org/docs/Xprint_FAQ.html), Xprint main site (http://xprint.mozdev.org/) +.SH AUTHORS +This manual page was written by +Roland Mainz <roland.mainz@nrubsig.org> based on the original X11R6.6 +\fBxc/programs/Xserver/XpConfig/README\fR. diff --git a/doc/xorg-docs/man/general/Xprint.sgml b/doc/xorg-docs/man/general/Xprint.sgml new file mode 100644 index 000000000..1f7e0a75e --- /dev/null +++ b/doc/xorg-docs/man/general/Xprint.sgml @@ -0,0 +1,627 @@ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.2//EN" 'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'> + +<!-- Process this file with docbook-to-man to generate an nroff manual + page: 'docbook-to-man manpage.sgml > manpage.1'. You may view + the manual page with: 'docbook-to-man manpage.sgml | nroff -man | less'. + A typical entry in a Makefile or Makefile.am is: + +manpage.1: manpage.sgml + docbook-to-man $< > $@ + +HTML generation can be done like this: +% xsltproc ==docbook /usr/share/sgml/docbook/docbook-xsl-stylesheets-1.60.1/html/docbook.xsl Xprint.sgml >Xprint.html + --> + +<refentry id="Xprint"> + <refmeta> + <refentrytitle>Xprint</refentrytitle> + <manvolnum>__miscmansuffix__</manvolnum> + </refmeta> + <refnamediv> + <refname>Xprint</refname> + + <refpurpose>The "X print service" - a portable, network-transparent printing system based on the X11 protocol</refpurpose> + </refnamediv> + <refsynopsisdiv> + <para>Xprint is a very flexible, extensible, scaleable, client/server + print system based on ISO 10175 (and some other specs) and the X11 + rendering protocol. + Using Xprint an application can search, query and use devices like + printers, FAX machines or create documents in formats like PDF. + In particular, an application can seek a printer, query supported + attributes (like paper size, trays, fonts etc.), configure the printer + device to match it’s needs and print on it like on any other X device + reusing parts of the code which is used for the video card Xserver. + </para> + </refsynopsisdiv> + + <refsect1> + <title>OVERVIEW</title> + <para> + The "X Print Service" technology allows X rendering to devices such as + printers and fax. Most of the service is available in the X11 + technology stack as Xp, with the remainder in single toolkit stacks (e.g. DtPrint for CDE). + Modifications have also been made to the LessTif/Motif/Qt technology + stacks to support Xprint. + </para> + <para> + The Xp portion consists of: + <itemizedlist> + <listitem><para>Xp Extension for the X-Server (included in the X-Server Xprt)</para></listitem> + <listitem><para>Xp Extension API for the client side (libXp/libXprintUtils)</para></listitem> + <listitem><para>PCL ddx driver that converts core X to native PCL</para></listitem> + <listitem><para>PDF ddx driver that converts core X to native PDF</para></listitem> + <listitem><para>PostScript ddx driver that converts core X to native PostScript</para></listitem> + <listitem><para>Raster ddx driver that generates xwd rasters which can be converted to PCL, PDF or PostScript rasters</para></listitem> + </itemizedlist> + </para> + <para> + From an X clients perspective, it can attach to one of two nearly + identical X-Servers, a "Video" X-Server, and a "Print" X-Server + which has the additional Xp capability but otherwise looks and + behaves the same. + </para> + </refsect1> + + <refsect1> + <title>HOW THE X PRINT SERVICE WORKS</title> + <para> + The X Print Service expands on the traditional X-Server and Xlib world + in four ways. + + <orderedlist> + <listitem> + <para> + Most obvious is the use of "print ddx drivers" instead of + "video ddx drivers". While a video ddx driver modifies pixels + in a video frame buffer, a print ddx driver generates "page + description language (PDL)" output (such as PCL, PDF or PostScript) + or sends the print rendering instructions to a platform-specific + print API (like Win32/GDI). + </para> + <para> + Once a print ddx driver generates PDL output, it can be sent to + a spooler such as <citerefentry><refentrytitle>lp</refentrytitle><manvolnum>1</manvolnum></citerefentry> + or retrieved by the client (to implement functionality like "print-to-file"). + </para> + <para> + Though not currently done, a single X-Server can support both + print and video ddx drivers. + <!-- FIXME: IBM/AIX people have integrated Xprt into their main Xserver (currently experimental) ... --> + </para> + </listitem> + <listitem> + <para> + Since printers support "paged" output, unlike video, a portion + of the Xp Extension supports APIs to delineate printed output. + For example, <function>XpStartPage</function> and <function>XpEndPage</function> tell the X-Server where + a physical page starts and ends in an otherwise continuous + stream of X rendering primitives. Likewise, <function>XpStartJob</function> and + <function>XpEndJob</function> determine when a collection of pages starts and ends. + <function>XpEndJob</function> typically causes the generated PDL to be submitted to + a spooler, such as <citerefentry><refentrytitle>lp</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + </listitem> + <listitem> + <para> + Since printers have extensive capabilities, another portion of + the Xp Extension supports APIs to manipulate "print contexts". + </para> + <para> + Once a printer is selected using the Xp Extension API, a print + context to represent it can be created. A print context + embodies the printer selected - it contains the printer's + default capabilities, selectable range of capabilities, + printer state, and generated output. Some "attributes" within + the print context can be modified by the user, and the + X-Server and print ddx driver will react accordingly. For + example, the attribute "content-orientation" can be set to + "landscape" or "portrait" (if the printer supports these + values - which can be queried using the Xprint API as well). + </para> + </listitem> + <listitem> + <para> + Since printers can have "built in" fonts, the Xp Extension in + the X-Server works with the print ddx drivers to make + available (for printing only) additional fonts on a per print + context basis. + </para> + <para> + When a print context is created and set for a given printer, + the X font calls may be able to access additional printer + fonts. To do this (typically), the X-Server must have access + to "printer metric files" (.pmf) that describe at minimum the + metrics of the built in fonts. + </para> + </listitem> + </orderedlist> + </para> + </refsect1> + + <refsect1> + <title>USAGE</title> + <para> + There are three tasks to start the X Print Service: + <orderedlist> + <listitem><para>configuring the X Print Server,</para></listitem> + <listitem><para>starting the X Print Service</para></listitem> + <listitem><para>configuring the user session so that clients can find the running X Print Service</para></listitem> + </orderedlist> + </para> + <para> + The tasks are described in detail below. + </para> + </refsect1> + + <refsect1> + <title>SERVER CONFIGURATION</title> + <para> + The X Print Server (Xprt) can read a number of configuration files which + control its behavior and support for printers. Each vendor platform has + a default location for this information. Xprt can also read the + environment variable <envar>XPCONFIGDIR</envar> to locate alternate configuration + directories. Common settings include: + + <simplelist type="vert"> + <member>export XPCONFIGDIR=/X11/lib/X11/XpConfig/</member> + <member>export XPCONFIGDIR=/proj/x11/xc/programs/Xserver/XpConfig/</member> + </simplelist> + </para> + <para> + Xprt has many built-in defaults, and lacking any configuration files, + will immediately try to support all printers visible via <citerefentry><refentrytitle>lpstat</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + <para> + In order of importance for configuration by a system administrator, the + configuration files for a "C" locale are as follows (see <citerefentry><refentrytitle>Xprt</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry> for more + details (including support for non-"C" locales)): + <variablelist> + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/Xprinters</filename></term> + <listitem> + <para> + 'Xprinters' is the top most configuration file. It tells + Xprt which specific printer names (e.g. mylaser) should + be supported, and whether <citerefentry><refentrytitle>lpstat</refentrytitle><manvolnum>1</manvolnum></citerefentry> or other commands + should be used to automatically supplement the list of + printers. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/attributes/printer</filename></term> + <listitem> + <para> + The 'printer' file maps printer names to model + configurations (see 'model-config' below). For example, + "mylaser" could be mapped to a "HPDJ1600C", and all other + arbitrary printers could be mapped to a default, such as + "HPLJ4SI". When depending on <citerefentry><refentrytitle>lpstat</refentrytitle><manvolnum>1</manvolnum></citerefentry> in the Xprinters + file, setting up defaults in 'printer' becomes all the + more important. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/attributes/document</filename></term> + <listitem> + <para> + The 'document' file specifies the initial document values + for any print jobs. For example, which paper tray to + use, what default resolution, etc. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/attributes/job</filename></term> + <listitem> + <para> + The 'job' file specifies the initial job values for any + print jobs. For example, "notification-profile" can be + set so that when a print job is successfully sent to a + printer, e-mail is sent to the user. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/models/PSdefault/model-config</filename></term> + <term><filename>${XPCONFIGDIR}/C/print/models/PSdefault/fonts/fonts.dir</filename></term> + <term><filename>${XPCONFIGDIR}/C/print/models/PSdefault/fonts/9nb00051.pmf</filename></term> + <term><filename>${XPCONFIGDIR}/C/print/models/PSdefault/fonts/9nb00093.pmf</filename></term> + + <listitem> + <para> + The 'model-config' file has attributes that describe the + printer model’s capabilities and default settings. + Printer model fonts may also be present. The model-config + file also identifies the print ddx driver to be used. + + For each printer model supported, a complete hierarchy of + files should exist. In most cases, these files do not + need to be modified. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>${XPCONFIGDIR}/C/print/ddx-config/raster/pcl</filename></term> + <term><filename>${XPCONFIGDIR}/C/print/ddx-config/raster/pdf</filename></term> + <term><filename>${XPCONFIGDIR}/C/print/ddx-config/raster/postscript</filename></term> + + <listitem> + <para> + The print ddx drivers can have highly specific + configuration files to control their behavior. In most + cases, these files do not need to be modified. + </para> + </listitem> + </varlistentry> + </variablelist> + + More information in how to configure and customize the X print server can be found in the + <citerefentry><refentrytitle>Xprt</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry> + manual page. + </para> + </refsect1> + + <refsect1> + <title>STARTING UP</title> + <para> + The summary checklist for starting the X Print Service is as follows: + + <orderedlist> + <listitem> + <para> + Choose an execution model for the X Print Service. The X + Print Service can be run on a per-user session basis, per + machine basis, or can be run on a few machines globally + available to a number of users. + </para> + </listitem> + <listitem> + <para> + If print jobs are to be submitted to a spooler (almost always + the case), make sure all needed printers are available to the + spooler subsystem (most often <citerefentry><refentrytitle>lp</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + on the same machine running the X Print Service. + </para> + </listitem> + <listitem> + <para> + Configure the X Print Server. See ``X Print Server + Configuration''. + </para> + </listitem> + <listitem> + <para> + Depending on #1, start the X Print Server process "Xprt", and + then the toolkit-specific Print Dialog Manager Daemon process + (such as CDEnext's "dtpdmd") at the appropriate times. + Note that libXprintUtils-based applications/toolkits do not need + a Print Dialog Manager Daemon process to use Xprint. + </para> + </listitem> + </orderedlist> + The details are described below. + </para> + <para> + Because the X Print Service is based on X, it can be easily distributed. + The most significant factors in which execution model to choose will be + driven by: + <itemizedlist> + <listitem> + <para> + how many printers will be accessable through the printer + subsystem on any given machine. A system administrator may + choose to cluster printers on a few given machines, or + scatter them across an organization and possibly make + extensive use of remote spoolers to make them globally + available. + </para> + </listitem> + <listitem> + <para> + how many machines will need a copy of the X Print Server + configuration files. The files have been architected so + that one super-set version of them can be maintained and + distributed (e.g. via NFS), and a per-machine or per-user + version of the `Xprinters' is all that is needed to have the + appropriate information in them utilized or ignored. + </para> + </listitem> + <listitem> + <para> + how many users can demand services from a given X Print + Service. + </para> + </listitem> + </itemizedlist> + + With the above in mind, some obvious execution models include: + <itemizedlist> + <listitem> + <para> + Global - in this model, the system administrator is choosing + to run the X Print Service on a *few* select machines with + appropriate printers configured, and allow clients access to + the global resource. This can centralize the administration + of printers and configuration files, but may have to be + monitored for performance loading. + </para> + <para> + Startup would likely be done by boot-up scripts (such as <filename>/etc/init.d/xprint</filename>). + </para> + </listitem> + + <listitem> + <para> + Per-machine - every machine with potential X Print Service + users would run the service. Printer and configuration file + administration is decentralized, and usage would be limited + to the users on the machine. + </para> + <para> + Startup would likely be done by boot-up scripts (such as <filename>/etc/init.d/xprint</filename>). + </para> + </listitem> + + <listitem> + <para> + Per-user session - every user would run an entire X Print + Service for themselves. In the future, the Video X Server + normally started may contain Print X Server capability, so + this model becomes very natural. + </para> + <para> + Startup would likely be done at session login or by + launching actions or processes manually once the user + logs in. Note: Deamons like "dtpdmd" must be started after Xprt. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Starting of the processes is straight forward. In strict order (example is for manually starting the X print server for CDEnext usage): + <orderedlist> + <listitem> + <para> + <programlisting>[machineA] % Xprt [-XpFile <Xprinters file>] [:dispNum] &</programlisting> + </para> + <para> + Note that Xprt will look for configuration files in either + a default location or where <envar>XPCONFIGDIR</envar> points. + </para> + <para> + <option>-XpFile</option> specifies an alternate `Xprinters' file, rather + than the default one or `<filename>${XPCONFIGDIR}/C/print/Xprinters</filename>'. + </para> + </listitem> + <listitem> + <para> + <programlisting>[machineA] % dtpdmd -d machineA[:dispNum] [-l /tmp/dtpdmd.log] &</programlisting> + </para> + <para> + The dtpdmd will maintain an X-Selection on the X-Server, + and will start dtpdm's as required to service requests. + </para> + </listitem> + </orderedlist> + </para> + <para> + In all but the per-user session model, the machine running the dtpdmd + (thus dtpdm's) will need display authorization to the users video + display. + </para> + </refsect1> + + <refsect1> + <title>CLIENT CONFIGURATION</title> + <para> + Once a X Print Server and dtpdmd have been started -- many of them + in some cases -- clients will need to find and use them. There are + two mechanisms that allow clients to discover X Print Servers and + printers. + + <itemizedlist> + <listitem> + <para> + "X Print Specifier" - assuming usage of the DtPrint/XprintUtils-based print + applications, the following notation is understood: + </para> + <para> + <programlisting>printer_name@machine[:dispNum]</programlisting> + </para> + <para> + For example: + </para> + <para> + <programlisting>colorlj7@printhub:2</programlisting> + </para> + <para> + In the above example, the X Print Server running at `printhub:2' + is assumed to support the printer named `colorlj7'. + </para> + </listitem> + <listitem> + <para> + <envar>${XPSERVERLIST}</envar> - assuming usage of the DtPrint print dialogs, + the environment variable <envar>${XPSERVERLIST}</envar> can contain a list + of X Print Servers. For example: + </para> + <para> + <programlisting>XPSERVERLIST="printhub:2 printhub:3 otherdept:0"</programlisting> + </para> + <para> + Then in the dialogs, only a printer name needs to be entered. + The dialog will then search the X Print Servers in <envar>${XPSERVERLIST}</envar> + for a server than supports the printer, and then establish + contact. + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + + <refsect1> + <title>END-USER SEQUENCE</title> + <para> + From most CDEnext applications, printing is accomplished by bringing + down the <File> menu and selecting <Print...>. This will result in + the DtPrintSetupBox dialog, which will request the name of a printer, + and offer limited capability to configure print options (e.g. number + of copies). If the user wishes, they can select <Setup...>, which + will start a dtpdm capable of modifying additional print options. + Finally, the user should select <Print>. + </para> + </refsect1> + + <refsect1> + <title>ENVIRONMENT</title> + <variablelist> + <varlistentry> + <term><envar>${XPCONFIGDIR}</envar></term> + <listitem> + <para> This environment variable points to the root + of the Xprint server configuration directory hierarchy. + If the variable is not defined, the default + path is be assumed. The default path may be + <filename>/usr/X11R6/lib/X11/xserver/</filename>, + <filename>/usr/lib/X11/xserver/</filename>, + <filename>/usr/share/Xprint/xserver/</filename> or + <filename>/usr/openwin/server/etc/XpConfig</filename>, depending on the + system, and may be configured in <filename>/etc/init.d/xprint</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>${LANG}</envar></term> + <listitem> + <para> + This environment variable selects the locale settings used by the Xprint server. + Xprt allows language-specific settings (stored in <filename>${XPCONFIGDIR}/${LANG}/print/</filename>) + which will override the default settings (stored in <filename>${XPCONFIGDIR}/C/print/</filename>). + If <envar>${LANG}</envar> is not set "C" is assumed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>${XPSERVERLIST}</envar></term> + <listitem> + <para>The environment variable <envar>${XPSERVERLIST}</envar> contains a list + of display identifiers (separated by whitespace) which tell an + application where it can find the Xprint servers. Usually + <envar>${XPSERVERLIST}</envar> is set by the profile startup scripts (e.g. + <filename>/etc/profile</filename> or <filename>/etc/profile.d/xprint.sh</filename>) using the output of + <userinput>/etc/init.d/xprint get_xpserverlist</userinput>.</para> + <para>Example: + <informalexample> + <programlisting> + export XPSERVERLIST="`/etc/init.d/xprint get_xpserverlist`"</programlisting> + </informalexample> + </para> + <para>Alternatively <envar>${XPSERVERLIST}</envar> can be set + manually. Example:</para> + <informalexample> + <programlisting> + export XPSERVERLIST="littlecat:80 bitdog:72"</programlisting> + </informalexample> + <para> + instructs an application to find an Xprint server at display + 80 on the machine "littlecat" and at display 72 on the + machine bigdog. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>${XPRINTER}</envar> + </term> + <listitem> + <para>The environment variable <envar>${XPRINTER}</envar> + defines the default printer used by print + applications. The syntax is either + <replaceable>printername</replaceable> or + <replaceable>printername</replaceable>@<replaceable>display</replaceable>.</para> + <para>Examples: + <variablelist> + <varlistentry> + <term><userinput>XPRINTER=ps003</userinput></term> + <listitem><para> + tells an application to look for the + first printer named "ps003" on all Xprint + servers.</para> + </listitem> + </varlistentry> + + <varlistentry> + <!-- brain dead <term> does not permit quote marks + (in XPRINTER="hplaser19@littlecat:80"), so omit them --> + <term><userinput>XPRINTER=hplaser19@littlecat:80</userinput></term> + <listitem><para> + tells an application to use the printer "hplaser19" + on the Xprint server at display + "littlecat:80".</para> + </listitem> + </varlistentry> + + </variablelist> + </para> + <para>If <envar>${XPRINTER}</envar> is not set the applications + will examine the values of the <envar>${PDPRINTER}</envar>, + <envar>${LPDEST}</envar>, and + <envar>${PRINTER}</envar> environment variables (in that order). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>SEE ALSO</title> + <para> + <simplelist type="inline"> + <!-- specific references --> + <!-- none --> + + <!-- Xprint general references --> +<!-- + <member><citerefentry><refentrytitle>Xprint</refentrytitle><manvolnum>__miscmansuffix__</manvolnum></citerefentry></member> +--> + <member><citerefentry><refentrytitle>X11</refentrytitle><manvolnum>__miscmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xplsprinters</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xprehashprinterlist</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xphelloworld</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xpxmhelloworld</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xpawhelloworld</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xpxthelloworld</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>xpsimplehelloworld</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>Xserver</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>Xprt</refentrytitle><manvolnum>__appmansuffix__</manvolnum></citerefentry></member> + <!-- ToDO: Add manual pages for the single Xprint DDX implementations (PostScript/PDF/PCL/PCL-MONO/Raster/etc.) --> + <member><citerefentry><refentrytitle>libXp</refentrytitle><manvolnum>__libmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>libXprintUtils</refentrytitle><manvolnum>__libmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>libXprintAppUtils</refentrytitle><manvolnum>__libmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>XmPrintShell</refentrytitle><manvolnum>__libmansuffix__</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>XawPrintShell</refentrytitle><manvolnum>__libmansuffix__</manvolnum></citerefentry></member> + <member>Xprint FAQ (<ulink url="http://xprint.mozdev.org/docs/Xprint_FAQ.html">http://xprint.mozdev.org/docs/Xprint_FAQ.html</ulink>)</member> + <member>Xprint main site (<ulink url="http://xprint.mozdev.org/">http://xprint.mozdev.org/</ulink>)</member> + </simplelist> + </para> + </refsect1> + + <refsect1> + <title>AUTHORS</title> + <para> + This manual page was written by + Roland Mainz <email>roland.mainz@nrubsig.org</email> based on the original X11R6.6 + <filename>xc/programs/Xserver/XpConfig/README</filename>. + </para> + </refsect1> +</refentry> + diff --git a/doc/xorg-docs/man/general/security.man b/doc/xorg-docs/man/general/security.man new file mode 100644 index 000000000..c2be69256 --- /dev/null +++ b/doc/xorg-docs/man/general/security.man @@ -0,0 +1,290 @@ +.\" $Xorg: security.cpp,v 1.3 2000/08/17 19:42:05 cpqbld Exp $ +.\" $XdotOrg: $ +.\" Copyright (c) 1993, 1994 X Consortium +.\" Copyright 2004 Sun Microsystems, Inc. +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, and/or sell copies of the Software, and to permit persons +.\" to whom the Software is furnished to do so, provided that the above +.\" copyright notice(s) and this permission notice appear in all copies of +.\" the Software and that both the above copyright notice(s) and this +.\" permission notice appear in supporting documentation. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR +.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL +.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Except as contained in this notice, the name of a copyright holder +.\" shall not be used in advertising or otherwise to promote the sale, use +.\" or other dealings in this Software without prior written authorization +.\" of the copyright holder. +.\" +.\" X Window System is a trademark of The Open Group. +.\" +.\" $XFree86: xc/doc/man/general/security.man,v 1.4tsi Exp $ +.\" +.nr )S 12 +.TH XSECURITY __miscmansuffix__ __xorgversion__ +.SH NAME +Xsecurity \- X display access control +.SH SYNOPSIS +.PP +X provides mechanism for implementing many access control systems. +The sample implementation includes six mechanisms: +.nf +.br +.ta 3.4i + Host Access Simple host-based access control. + MIT-MAGIC-COOKIE-1 Shared plain-text "cookies". + XDM-AUTHORIZATION-1 Secure DES based private-keys. + SUN-DES-1 Based on Sun's secure rpc system. + MIT-KERBEROS-5 Kerberos Version 5 user-to-user. + Server Interpreted Server-dependent methods of access control +.fi +Not all of these are available in all builds or implementations. +.SH "ACCESS SYSTEM DESCRIPTIONS" +.IP "Host Access" +Any client on a host in the host access control list is allowed access to +the X server. This system can work reasonably well in an environment +where everyone trusts everyone, or when only a single person can log in +to a given machine, and is easy to use when the list of hosts used is small. +This system does not work well when multiple people can log in to a single +machine and mutual trust does not exist. +The list of allowed hosts is stored in the X server and can be changed with +the \fIxhost\fP command. The list is stored in the server by network +address, not host names, so is not automatically updated if a host changes +address while the server is running. +When using the more secure mechanisms listed below, the host list is +normally configured to be the empty list, so that only authorized +programs can connect to the display. See the GRANTING ACCESS section of +the \fIXserver\fP man page for details on how this list is initialized at +server startup. +.IP "MIT-MAGIC-COOKIE-1" +When using MIT-MAGIC-COOKIE-1, +the client sends a 128 bit "cookie" +along with the connection setup information. +If the cookie presented by the client matches one +that the X server has, the connection is allowed access. +The cookie is chosen so that it is hard to guess; +\fIxdm\fP generates such cookies automatically when this form of +access control is used. +The user's copy of +the cookie is usually stored in the \fI.Xauthority\fP file in the home +directory, although the environment variable \fBXAUTHORITY\fP can be used +to specify an alternate location. +\fIXdm\fP automatically passes a cookie to the server for each new +login session, and stores the cookie in the user file at login. +.IP +The cookie is transmitted on the network without encryption, so +there is nothing to prevent a network snooper from obtaining the data +and using it to gain access to the X server. This system is useful in an +environment where many users are running applications on the same machine +and want to avoid interference from each other, with the caveat that this +control is only as good as the access control to the physical network. +In environments where network-level snooping is difficult, this system +can work reasonably well. +.IP "XDM-AUTHORIZATION-1" +Sites who compile with DES support can use a DES-based access control +mechanism called XDM-AUTHORIZATION-1. +It is similar in usage to MIT-MAGIC-COOKIE-1 in that a key is +stored in the \fI.Xauthority\fP file and is shared with the X server. +However, +this key consists of two parts - a 56 bit DES encryption key and 64 bits of +random data used as the authenticator. +.IP +When connecting to the X server, the application generates 192 bits of data +by combining the current time in seconds (since 00:00 1/1/1970 GMT) along +with 48 bits of "identifier". For TCP/IPv4 connections, the identifier is +the address plus port number; for local connections it is the process ID +and 32 bits to form a unique id (in case multiple connections to the same +server are made from a single process). This 192 bit packet is then +encrypted using the DES key and sent to the X server, which is able to +verify if the requestor is authorized to connect by decrypting with the +same DES key and validating the authenticator and additional data. +This system is useful in many environments where host-based access control +is inappropriate and where network security cannot be ensured. +.IP "SUN-DES-1" +Recent versions of SunOS (and some other systems) have included a +secure public key remote procedure call system. This system is based +on the notion of a network principal; a user name and NIS domain pair. +Using this system, the X server can securely discover the actual user +name of the requesting process. It involves encrypting data with the +X server's public key, and so the identity of the user who started the +X server is needed for this; this identity is stored in the \fI.Xauthority\fP +file. By extending the semantics of "host address" to include this notion of +network principal, this form of access control is very easy to use. +.IP +To allow access by a new user, use \fIxhost\fP. For example, +.nf + xhost keith@ ruth@mit.edu +.fi +adds "keith" from the NIS domain of the local machine, and "ruth" in +the "mit.edu" NIS domain. For keith or ruth to successfully connect +to the display, they must add the principal who started the server to +their \fI.Xauthority\fP file. For example: +.nf + xauth add expo.lcs.mit.edu:0 SUN-DES-1 unix.expo.lcs.mit.edu@our.domain.edu +.fi +This system only works on machines which support Secure RPC, and only for +users which have set up the appropriate public/private key pairs on their +system. See the Secure RPC documentation for details. +To access the display from a remote host, you may have to do a +\fIkeylogin\fP on the remote host first. +.IP MIT-KERBEROS-5 +Kerberos is a network-based authentication scheme developed by MIT for +Project Athena. It allows mutually suspicious principals to +authenticate each other as long as each trusts a third party, +Kerberos. Each principal has a secret key known only to it and +Kerberos. Principals includes servers, such as an FTP server or X +server, and human users, whose key is their password. Users gain +access to services by getting Kerberos tickets for those services from +a Kerberos server. Since the X server has no place to store a secret +key, it shares keys with the user who logs in. X authentication thus +uses the user-to-user scheme of Kerberos version 5. +.IP +When you log in via \fIxdm\fP, \fIxdm\fP will use your password to +obtain the initial Kerberos tickets. \fIxdm\fP stores the tickets in +a credentials cache file and sets the environment variable +\fIKRB5CCNAME\fP to point to the file. The credentials cache is +destroyed when the session ends to reduce the chance of the tickets +being stolen before they expire. +.IP +Since Kerberos is a user-based authorization protocol, like the +SUN-DES-1 protocol, the owner of a display can enable +and disable specific users, or Kerberos principals. +The \fIxhost\fP client is used to enable or disable authorization. +For example, +.nf + xhost krb5:judy krb5:gildea@x.org +.fi +adds "judy" from the Kerberos realm of the local machine, and "gildea" +from the "x.org" realm. +.IP "Server Interpreted" +The Server Interpreted method provides two strings to the X server for +entry in the access control list. The first string represents the type +of entry, and the second string contains the value of the entry. These +strings are interpreted by the server and different implementations and +builds may support different types of entries. The types supported in +the sample implementation are defined in the SERVER INTERPRETED ACCESS +TYPES section below. Entries of this type can be manipulated via +\fIxhost\fP. For example to add a Server Interpreted entry of type +localuser with a value of root, the command is \fBxhost +si:localuser:root\fP. +.SH "THE AUTHORIZATION FILE" +.PP +Except for Host Access control and Server Interpreted Access Control, each of +these systems uses data stored in +the \fI.Xauthority\fP file to generate the correct authorization information +to pass along to the X server at connection setup. MIT-MAGIC-COOKIE-1 and +XDM-AUTHORIZATION-1 store secret data in the file; so anyone who can read +the file can gain access to the X server. SUN-DES-1 stores only the +identity of the principal who started the server +(unix.\fIhostname\fP@\fIdomain\fP when the server is started by \fIxdm\fP), +and so it is not useful to anyone not authorized to connect to the server. +.PP +Each entry in the \fI.Xauthority\fP file matches a certain connection family +(TCP/IP, DECnet or local connections) and X display name (hostname plus display +number). This allows multiple authorization entries for different displays +to share the same data file. A special connection family (FamilyWild, value +65535) causes an entry to match every display, allowing the entry to be used +for all connections. Each entry additionally contains the authorization +name and whatever private authorization data is needed by that authorization +type to generate the correct information at connection setup time. +.PP +The \fIxauth\fP program manipulates the \fI.Xauthority\fP file format. +It understands the semantics of the connection families and address formats, +displaying them in an easy to understand format. It also understands that +SUN-DES-1 and MIT-KERBEROS-5 use +string values for the authorization data, and displays +them appropriately. +.PP +The X server (when running on a workstation) reads authorization +information from a file name passed on the command line with the \fI\-auth\fP +option (see the \fIXserver\fP manual page). The authorization entries in +the file are used to control access to the server. In each of the +authorization schemes listed above, the data needed by the server to initialize +an authorization scheme is identical to the data needed by the client to +generate the appropriate authorization information, so the same file can be +used by both processes. This is especially useful when \fIxinit\fP is used. +.IP "MIT-MAGIC-COOKIE-1" +This system uses 128 bits of data shared between the user and the X server. +Any collection of bits can be used. \fIXdm\fP generates these keys using a +cryptographically secure pseudo random number generator, and so the key to +the next session cannot be computed from the current session key. +.IP "XDM-AUTHORIZATION-1" +This system uses two pieces of information. First, 64 bits of random data, +second a 56 bit DES encryption key (again, random data) stored +in 8 bytes, the last byte of which is ignored. \fIXdm\fP generates these keys +using the same random number generator as is used for MIT-MAGIC-COOKIE-1. +.IP "SUN-DES-1" +This system needs a string representation of the principal which identifies +the associated X server. +This information is used to encrypt the client's authority information +when it is sent to the X server. +When \fIxdm\fP starts the X server, it uses the root +principal for the machine on which it is running +(unix.\fIhostname\fP@\fIdomain\fP, e.g., +"unix.expire.lcs.mit.edu@our.domain.edu"). Putting the correct principal +name in the \fI.Xauthority\fP file causes Xlib to generate the appropriate +authorization information using the secure RPC library. +.IP "MIT-KERBEROS-5" +Kerberos reads tickets from the cache pointed to by the +\fIKRB5CCNAME\fP environment variable, so does not use any data from +the \fI.Xauthority\fP file. An entry with no data must still exist to tell +clients that MIT-KERBEROS-5 is available. +.IP +Unlike the \fI.Xauthority\fP file for clients, the authority file +passed by xdm to +a local X server (with ``\fB\-auth\fP \fIfilename\fP'', see xdm(1)) +does contain the name of the credentials cache, since +the X server will not have the +\fIKRB5CCNAME\fP environment variable set. +The data of the MIT-KERBEROS-5 entry is the credentials cache name and +has the form ``UU:FILE:\fIfilename\fP'', where \fIfilename\fP is the +name of the credentials cache file created by xdm. Note again that +this form is \fInot\fP used by clients. +.SH "SERVER INTERPRETED ACCESS TYPES" +The sample implementation includes several Server Interpreted mechanisms: +.nf +.br +.ta 3.4i + IPv6 IPv6 literal addresses + hostname Network host name + localuser Local connection user id + localgroup Local connection group id +.fi +.IP "IPv6" +A literal IPv6 address as defined in IETF RFC 3513. +.IP "hostname" +The value must be a hostname as defined in IETF RFC 2396. Due to Mobile IP +and dynamic DNS, the name service is consulted at connection +authentication time, unlike the traditional host access control list +which only contains numeric addresses and does not automatically update when +a host's address changes. Note that this definition of hostname does +not allow use of literal IP addresses. +.IP "localuser & localgroup" +On systems which can determine in a secure fashion the credentials of a client +process, the "localuser" and "localgroup" authentication methods provide access +based on those credentials. The format of the values provided is platform +specific. For POSIX & UNIX platforms, if the value starts with the +character '#', the rest of the string is treated as a decimal uid or gid, +otherwise the string is defined as a user name or group name. +.IP +If your system supports this method and you use it, be warned that some +programs that proxy connections and are setuid or setgid may get authenticated +as the uid or gid of the proxy process. For instance, some versions of ssh +will be authenticated as the user root, no matter what user is running the +ssh client, so on systems with such software, adding access for localuser:root +may allow wider access than intended to the X display. +.SH FILES +\&.Xauthority +.SH "SEE ALSO" +X(__miscmansuffix__), xdm(1), xauth(1), xhost(1), xinit(1), Xserver(1) |