xrdb/man/xrdb.man

   1 .\" Copyright 1991, Digital Equipment Corporation.
   2 .\" Copyright 1991, 1994, 1998  The Open Group
   3 .\"
   4 .\" Permission to use, copy, modify, distribute, and sell this software and its
   5 .\" documentation for any purpose is hereby granted without fee, provided that
   6 .\" the above copyright notice appear in all copies and that both that
   7 .\" copyright notice and this permission notice appear in supporting
   8 .\" documentation.
   9 .\"
  10 .\" The above copyright notice and this permission notice shall be included
  11 .\" in all copies or substantial portions of the Software.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  14 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  15 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  16 .\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
  17 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  18 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  19 .\" OTHER DEALINGS IN THE SOFTWARE.
  20 .\"
  21 .\" Except as contained in this notice, the name of The Open Group shall
  22 .\" not be used in advertising or otherwise to promote the sale, use or
  23 .\" other dealings in this Software without prior written authorization
  24 .\" from The Open Group.
  25 .\"
  26 .TH XRDB 1 __xorgversion__
  27 .SH NAME
  28 xrdb - X server resource database utility
  29 .SH SYNOPSIS
  30 .B xrdb
  31 [-option ...] [\fIfilename\fP]
  32 .SH DESCRIPTION
  33 .I Xrdb
  34 is used to get or set the contents of the RESOURCE_MANAGER property
  35 on the root window of screen 0, or the SCREEN_RESOURCES property on
  36 the root window of any or all screens, or everything combined.
  37 You would normally run this program from your X startup file.
  38 .LP
  39 Most X clients use the RESOURCE_MANAGER and SCREEN_RESOURCES properties to
  40 get user preferences about
  41 color, fonts, and so on for applications.  Having this information in
  42 the server (where it is available to all clients) instead of on disk,
  43 solves the problem in previous versions of X that required you to
  44 maintain \fIdefaults\fP files on every machine that you might use.
  45 It also allows for dynamic changing of defaults without editing files.
  46 .LP
  47 The RESOURCE_MANAGER property is used for resources that apply to all
  48 screens of the display.  The SCREEN_RESOURCES property on each screen
  49 specifies additional (or overriding) resources to be used for that screen.
  50 (When there is only one screen, SCREEN_RESOURCES is normally not used,
  51 all resources are just placed in the RESOURCE_MANAGER property.)
  52 .LP
  53 The file specified by
  54 .I filename
  55 (or the contents from standard input if - or no filename is given)
  56 is optionally passed through the C preprocessor with the
  57 following symbols defined, based on the capabilities of the server
  58 being used:
  59 .TP 8
  60 .B SERVERHOST=\fIhostname\fP
  61 the hostname portion of the display to which you are connected.
  62 .TP 8
  63 .B SRVR_\fIname\fB
  64 the SERVERHOST hostname string turned into a legal identifier.
  65 For example, "my-dpy.lcs.mit.edu" becomes SRVR_my_dpy_lcs_mit_edu.
  66 .TP 8
  67 .B HOST=\fIhostname\fP
  68 the same as
  69 .BR SERVERHOST .
  70 .TP 8
  71 .B DISPLAY_NUM=\fInum\fP
  72 the number of the display on the server host.
  73 .TP 8
  74 .B CLIENTHOST=\fIhostname\fP
  75 the name of the host on which
  76 .I xrdb
  77 is running.
  78 .TP 8
  79 .B CLNT_\fIname\fB
  80 the CLIENTHOST hostname string turned into a legal identifier.
  81 For example, "expo.lcs.mit.edu" becomes CLNT_expo_lcs_mit_edu.
  82 .TP 8
  83 .B RELEASE=\fInum\fP
  84 the vendor release number for the server.  The interpretation of this
  85 number will vary depending on VENDOR.
  86 .TP 8
  87 .B REVISION=\fInum\fP
  88 the X protocol minor version supported by this server (currently 0).
  89 .TP 8
  90 .B VERSION=\fInum\fP
  91 the X protocol major version supported by this server (should always be 11).
  92 .TP 8
  93 .B VENDOR="\fIvendor\fP"
  94 a string literal specifying the vendor of the server.
  95 .TP 8
  96 .B VNDR_\fIname\fP
  97 the VENDOR name string turned into a legal identifier.
  98 For example, "MIT X Consortium" becomes VNDR_MIT_X_Consortium.
  99 .TP 8
 100 .B EXT_\fIname\fP
 101 A symbol is defined for each protocol extension supported by the server.
 102 Each extension string name is turned into a legal identifier.
 103 For example, "X3D-PEX" becomes EXT_X3D_PEX.
 104 .TP 8
 105 .B NUM_SCREENS=\fInum\fP
 106 the total number of screens.
 107 .TP 8
 108 .B SCREEN_NUM=\fInum\fP
 109 the number of the current screen (from zero).
 110 .TP 8
 111 .B BITS_PER_RGB=\fInum\fP
 112 the number of significant bits in an RGB color specification.  This is the
 113 log base 2 of the number of distinct shades of each primary that the hardware
 114 can generate.  Note that it usually is not related to PLANES.
 115 .TP 8
 116 .B CLASS=\fIvisualclass\fP
 117 one of StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor,
 118 DirectColor.  This is the visual class of the root window.
 119 .TP 8
 120 .B CLASS_\fIvisualclass\fP=\fIvisualid\fP
 121 the visual class of the root window in a form you can \fI#ifdef\fP on.
 122 The value is the numeric id of the visual.
 123 .TP 8
 124 .B COLOR
 125 defined only if CLASS is one of StaticColor, PseudoColor, TrueColor, or
 126 DirectColor.
 127 .TP 8
 128 .B CLASS_\fIvisualclass\fP_\fIdepth\fP=\fInum\fP
 129 A symbol is defined for each visual supported for the screen.
 130 The symbol includes the class of the visual and its depth;
 131 the value is the numeric id of the visual.
 132 (If more than one visual has the same class and depth, the numeric id
 133 of the first one reported by the server is used.)
 134 .TP 8
 135 .B HEIGHT=\fInum\fP
 136 the height of the root window in pixels.
 137 .TP 8
 138 .B WIDTH=\fInum\fP
 139 the width of the root window in pixels.
 140 .TP 8
 141 .B PLANES=\fInum\fP
 142 the number of bit planes (the depth) of the root window.
 143 .TP 8
 144 .B X_RESOLUTION=\fInum\fP
 145 the x resolution of the screen in pixels per meter.
 146 .TP 8
 147 .B Y_RESOLUTION=\fInum\fP
 148 the y resolution of the screen in pixels per meter.
 149 .LP
 150 SRVR_\fIname\fP, CLNT_\fIname\fP, VNDR_\fIname\fP, and EXT_\fIname\fP
 151 identifiers are formed by changing all characters other than letters
 152 and digits into underscores (_).
 153 .LP
 154 Lines that begin with an exclamation mark (!) are ignored and may
 155 be used as comments.
 156 .LP
 157 Note that since
 158 .I xrdb
 159 can read from standard input, it can be used to
 160 the change the contents of properties directly from
 161 a terminal or from a shell script.
 162 .SH "OPTIONS"
 163 .PP
 164 .I xrdb
 165 program accepts the following options:
 166 .TP 8
 167 .B \-help
 168 This option (or any unsupported option) will cause a brief description of
 169 the allowable options and parameters to be printed.
 170 .TP 8
 171 .B \-display \fIdisplay\fP
 172 This option specifies the X server to be used; see \fIX(__miscmansuffix__)\fP.
 173 It also specifies the screen to use for the \fI-screen\fP option,
 174 and it specifies the screen from which preprocessor symbols are
 175 derived for the \fI-global\fP option.
 176 .TP 8
 177 .B \-all
 178 This option indicates that operation should be performed on the
 179 screen-independent resource property (RESOURCE_MANAGER), as well as
 180 the screen-specific property (SCREEN_RESOURCES) on every screen of the
 181 display.  For example, when used in conjunction with \fI-query\fP,
 182 the contents of all properties are output.  For \fI-load\fP, \fI-override\fP
 183 and \fI-merge\fP,
 184 the input file is processed once for each screen.  The resources which occur
 185 in common in the output for every screen are collected, and these are applied
 186 as the screen-independent resources.  The remaining resources are applied
 187 for each individual per-screen property.  This the default mode of operation.
 188 .TP 8
 189 .B \-global
 190 This option indicates that the operation should only be performed on
 191 the screen-independent RESOURCE_MANAGER property.
 192 .TP 8
 193 .B \-screen
 194 This option indicates that the operation should only be performed on
 195 the SCREEN_RESOURCES property of the default screen of the display.
 196 .TP 8
 197 .B \-screens
 198 This option indicates that the operation should be performed on
 199 the SCREEN_RESOURCES property of each screen of the display.
 200 For \fI-load\fP, \fI-override\fP and \fI-merge\fP, the input file is
 201 processed for each screen.
 202 .TP 8
 203 .B \-n
 204 This option indicates that changes to the specified properties (when used with
 205 \fI-load\fP, \fI-override\fP or \fI-merge\fP)
 206 or to the resource file (when used with \fI-edit\fP) should be shown on the
 207 standard output, but should not be performed.
 208 .TP 8
 209 .B \-quiet
 210 This option indicates that warning about duplicate entries should not be
 211 displayed.
 212 .TP 8
 213 .B -cpp \fIfilename\fP
 214 This option specifies the pathname of the C preprocessor program to be used.
 215 Although
 216 .I xrdb
 217 was designed to use CPP, any program that acts as a filter
 218 and accepts the -D, -I, and -U options may be used.
 219 .TP 8
 220 .B -nocpp
 221 This option indicates that
 222 .I xrdb
 223 should not run the input file through a preprocessor before loading it
 224 into properties.
 225 .TP 8
 226 .B \-symbols
 227 This option indicates that the symbols that are defined for the preprocessor
 228 should be printed onto the standard output.
 229 .TP 8
 230 .B \-query
 231 This option indicates that the current contents of the specified
 232 properties should be printed onto the standard output.  Note that since
 233 preprocessor commands in the input resource file are part of the input
 234 file, not part of the property, they won't appear in the output from this
 235 option.  The
 236 .B \-edit
 237 option can be used to merge the contents of properties back into the input
 238 resource file without damaging preprocessor commands.
 239 .TP 8
 240 .B \-load
 241 This option indicates that the input should be loaded as the new value
 242 of the specified properties, replacing whatever was there (i.e.
 243 the old contents are removed).  This is the default action.
 244 .TP 8
 245 .B \-override
 246 This option indicates that the input should be added to, instead of
 247 replacing, the current contents of the specified properties.
 248 New entries override previous entries.
 249 .TP 8
 250 .B \-merge
 251 This option indicates that the input should be merged and lexicographically
 252 sorted with, instead of replacing, the current contents of the specified
 253 properties.
 254 .TP 8
 255 .B \-remove
 256 This option indicates that the specified properties should be removed
 257 from the server.
 258 .TP 8
 259 .B \-retain
 260 This option indicates that the server should be instructed not to reset if
 261 \fIxrdb\fP is the first client.  This should never be necessary under normal
 262 conditions, since \fIxdm\fP and \fIxinit\fP always act as the first client.
 263 .TP 8
 264 .B \-edit \fIfilename\fP
 265 This option indicates that the contents of the specified properties
 266 should be edited into the given file, replacing any values already listed
 267 there.  This allows you to put changes that you have made to your defaults
 268 back into your resource file, preserving any comments or preprocessor lines.
 269 .TP 8
 270 .B \-backup \fIstring\fP
 271 This option specifies a suffix to be appended to the filename used with
 272 .B \-edit
 273 to generate a backup file.
 274 .TP 8
 275 .B \-D\fIname[=value]\fP
 276 This option is passed through to the preprocessor and is used to define
 277 symbols for use with conditionals such as
 278 .I #ifdef.
 279 .TP 8
 280 .B \-U\fIname\fP
 281 This option is passed through to the preprocessor and is used to remove
 282 any definitions of this symbol.
 283 .TP 8
 284 .B \-I\fIdirectory\fP
 285 This option is passed through to the preprocessor and is used to specify
 286 a directory to search for files that are referenced with
 287 .I #include.
 288 .SH FILES
 289 Generalizes \fI~/.Xdefaults\fP files.
 290 .SH "SEE ALSO"
 291 X(__miscmansuffix__), appres(__appmansuffix__), listres(__appmansuffix__),
 292 Xlib Resource Manager documentation, Xt resource documentation
 293 .SH ENVIRONMENT
 294 .TP 8
 295 .B DISPLAY
 296 to figure out which display to use.
 297 .SH BUGS
 298 .PP
 299 The default for no arguments should be to query, not to overwrite, so that
 300 it is consistent with other programs.
 301 .SH AUTHORS
 302 Bob Scheifler, Phil Karlton, rewritten from the original by Jim Gettys