HP/util/HP/man/mann/registry.n

   1 '\"
   2 '\" Copyright (c) 1997 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" RCS: @(#) $Id: registry.n,v 1.4 1999/04/16 00:46:35 stanton Exp $
   8 '\"
   9 '\" The definitions below are for supplemental macros used in Tcl/Tk
  10 '\" manual entries.
  11 '\"
  12 '\" .AP type name in/out ?indent?
  13 '\"     Start paragraph describing an argument to a library procedure.
  14 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 '\"     needed;  use .AS below instead)
  18 '\"
  19 '\" .AS ?type? ?name?
  20 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 '\"     name are examples of largest possible arguments that will be passed
  22 '\"     to .AP later.  If args are omitted, default tab stops are used.
  23 '\"
  24 '\" .BS
  25 '\"     Start box enclosure.  From here until next .BE, everything will be
  26 '\"     enclosed in one large box.
  27 '\"
  28 '\" .BE
  29 '\"     End of box enclosure.
  30 '\"
  31 '\" .CS
  32 '\"     Begin code excerpt.
  33 '\"
  34 '\" .CE
  35 '\"     End code excerpt.
  36 '\"
  37 '\" .VS ?version? ?br?
  38 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 '\"     of man pages.  The first argument is ignored and used for recording
  40 '\"     the version when the .VS was added, so that the sidebars can be
  41 '\"     found and removed when they reach a certain age.  If another argument
  42 '\"     is present, then a line break is forced before starting the sidebar.
  43 '\"
  44 '\" .VE
  45 '\"     End of vertical sidebar.
  46 '\"
  47 '\" .DS
  48 '\"     Begin an indented unfilled display.
  49 '\"
  50 '\" .DE
  51 '\"     End of indented unfilled display.
  52 '\"
  53 '\" .SO
  54 '\"     Start of list of standard options for a Tk widget.  The
  55 '\"     options follow on successive lines, in four columns separated
  56 '\"     by tabs.
  57 '\"
  58 '\" .SE
  59 '\"     End of list of standard options for a Tk widget.
  60 '\"
  61 '\" .OP cmdName dbName dbClass
  62 '\"     Start of description of a specific option.  cmdName gives the
  63 '\"     option's name as specified in the class command, dbName gives
  64 '\"     the option's name in the option database, and dbClass gives
  65 '\"     the option's class in the option database.
  66 '\"
  67 '\" .UL arg1 arg2
  68 '\"     Print arg1 underlined, then print arg2 normally.
  69 '\"
  70 '\" RCS: @(#) $Id: man.macros,v 1.3 1999/04/16 00:46:35 stanton Exp $
  71 '\"
  72 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  73 .if t .wh -1.3i ^B
  74 .nr ^l \n(.l
  75 .ad b
  76 '\"     # Start an argument description
  77 .de AP
  78 .ie !"\\$4"" .TP \\$4
  79 .el \{\
  80 .   ie !"\\$2"" .TP \\n()Cu
  81 .   el          .TP 15
  82 .\}
  83 .ta \\n()Au \\n()Bu
  84 .ie !"\\$3"" \{\
  85 \&\\$1  \\fI\\$2\\fP    (\\$3)
  86 .\".b
  87 .\}
  88 .el \{\
  89 .br
  90 .ie !"\\$2"" \{\
  91 \&\\$1  \\fI\\$2\\fP
  92 .\}
  93 .el \{\
  94 \&\\fI\\$1\\fP
  95 .\}
  96 .\}
  97 ..
  98 '\"     # define tabbing values for .AP
  99 .de AS
 100 .nr )A 10n
 101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 102 .nr )B \\n()Au+15n
 103 .\"
 104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 106 ..
 107 .AS Tcl_Interp Tcl_CreateInterp in/out
 108 '\"     # BS - start boxed text
 109 '\"     # ^y = starting y location
 110 '\"     # ^b = 1
 111 .de BS
 112 .br
 113 .mk ^y
 114 .nr ^b 1u
 115 .if n .nf
 116 .if n .ti 0
 117 .if n \l'\\n(.lu\(ul'
 118 .if n .fi
 119 ..
 120 '\"     # BE - end boxed text (draw box now)
 121 .de BE
 122 .nf
 123 .ti 0
 124 .mk ^t
 125 .ie n \l'\\n(^lu\(ul'
 126 .el \{\
 127 .\"     Draw four-sided box normally, but don't draw top of
 128 .\"     box if the box started on an earlier page.
 129 .ie !\\n(^b-1 \{\
 130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 131 .\}
 132 .el \}\
 133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 134 .\}
 135 .\}
 136 .fi
 137 .br
 138 .nr ^b 0
 139 ..
 140 '\"     # VS - start vertical sidebar
 141 '\"     # ^Y = starting y location
 142 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 143 .de VS
 144 .if !"\\$2"" .br
 145 .mk ^Y
 146 .ie n 'mc \s12\(br\s0
 147 .el .nr ^v 1u
 148 ..
 149 '\"     # VE - end of vertical sidebar
 150 .de VE
 151 .ie n 'mc
 152 .el \{\
 153 .ev 2
 154 .nf
 155 .ti 0
 156 .mk ^t
 157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 158 .sp -1
 159 .fi
 160 .ev
 161 .\}
 162 .nr ^v 0
 163 ..
 164 '\"     # Special macro to handle page bottom:  finish off current
 165 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 166 '\"     # page bottom macro.
 167 .de ^B
 168 .ev 2
 169 'ti 0
 170 'nf
 171 .mk ^t
 172 .if \\n(^b \{\
 173 .\"     Draw three-sided box if this is the box's first page,
 174 .\"     draw two sides but no top otherwise.
 175 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 177 .\}
 178 .if \\n(^v \{\
 179 .nr ^x \\n(^tu+1v-\\n(^Yu
 180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 181 .\}
 182 .bp
 183 'fi
 184 .ev
 185 .if \\n(^b \{\
 186 .mk ^y
 187 .nr ^b 2
 188 .\}
 189 .if \\n(^v \{\
 190 .mk ^Y
 191 .\}
 192 ..
 193 '\"     # DS - begin display
 194 .de DS
 195 .RS
 196 .nf
 197 .sp
 198 ..
 199 '\"     # DE - end display
 200 .de DE
 201 .fi
 202 .RE
 203 .sp
 204 ..
 205 '\"     # SO - start of list of standard options
 206 .de SO
 207 .SH "STANDARD OPTIONS"
 208 .LP
 209 .nf
 210 .ta 4c 8c 12c
 211 .ft B
 212 ..
 213 '\"     # SE - end of list of standard options
 214 .de SE
 215 .fi
 216 .ft R
 217 .LP
 218 See the \\fBoptions\\fR manual entry for details on the standard options.
 219 ..
 220 '\"     # OP - start of full description for a single option
 221 .de OP
 222 .LP
 223 .nf
 224 .ta 4c
 225 Command-Line Name:      \\fB\\$1\\fR
 226 Database Name:  \\fB\\$2\\fR
 227 Database Class: \\fB\\$3\\fR
 228 .fi
 229 .IP
 230 ..
 231 '\"     # CS - begin code excerpt
 232 .de CS
 233 .RS
 234 .nf
 235 .ta .25i .5i .75i 1i
 236 ..
 237 '\"     # CE - end code excerpt
 238 .de CE
 239 .fi
 240 .RE
 241 ..
 242 .de UL
 243 \\$1\l'|0\(ul'\\$2
 244 ..
 245 .TH registry n 8.0 Tcl "Tcl Built-In Commands"
 246 .BS
 247 '\" Note:  do not modify the .SH NAME line immediately below!
 248 .SH NAME
 249 registry \- Manipulate the Windows registry
 250 .SH SYNOPSIS
 251 .sp
 252 \fBpackage require registry 1.0\fR
 253 .sp
 254 \fBregistry \fIoption\fR \fIkeyName\fR ?\fIarg arg ...\fR?
 255 .BE
 256
 257 .SH DESCRIPTION
 258 .PP
 259 The \fBregistry\fR package provides a general set of operations for
 260 manipulating the Windows registry.  The package implements the
 261 \fBregistry\fR Tcl command.  This command is only supported on the
 262 Windows platform.  Warning: this command should be used with caution
 263 as a corrupted registry can leave your system in an unusable state.
 264 .PP
 265 \fIKeyName\fR is the name of a registry key.  Registry keys must be
 266 one of the following forms:
 267 .IP
 268 \fB\e\e\fIhostname\fB\e\fIrootname\fB\e\fIkeypath\fR
 269 .IP
 270 \fIrootname\fB\e\fIkeypath\fR
 271 .IP
 272 \fIrootname\fR
 273 .PP
 274 \fIHostname\fR specifies the name of any valid Windows
 275 host that exports its registry.  The \fIrootname\fR component must be
 276 one of \fBHKEY_LOCAL_MACHINE\fR, \fBHKEY_USERS\fR,
 277 .VS
 278 \fBHKEY_CLASSES_ROOT\fR, \fBHKEY_CURRENT_USER\fR,
 279 \fBHKEY_CURRENT_CONFIG\fR, \fBHKEY_PERFORMANCE_DATA\fR, or
 280 \fBHKEY_DYN_DATA\fR.  The \fIkeypath\fR can be one or more
 281 .VE
 282 registry key names separated by backslash (\fB\e\fR) characters.
 283 .PP
 284 \fIOption\fR indicates what to do with the registry key name.  Any
 285 unique abbreviation for \fIoption\fR is acceptable.  The valid options
 286 are:
 287 .TP
 288 \fBregistry delete \fIkeyName\fR ?\fIvalueName\fR?
 289 .
 290 If the optional \fIvalueName\fR argument is present, the specified
 291 value under \fIkeyName\fR will be deleted from the registry.  If the
 292 optional \fIvalueName\fR is omitted, the specified key and any subkeys
 293 or values beneath it in the registry heirarchy will be deleted.  If
 294 the key could not be deleted then an error is generated.  If the key
 295 did not exist, the command has no effect.
 296 .TP
 297 \fBregistry get \fIkeyName valueName\fR
 298 .
 299 Returns the data associated with the value \fIvalueName\fR under the key
 300 \fIkeyName\fR.  If either the key or the value does not exist, then an
 301 error is generated.  For more details on the format of the returned
 302 data, see SUPPORTED TYPES, below.
 303 .TP
 304 \fBregistry keys \fIkeyName\fR ?\fIpattern\fR?
 305 .
 306 If \fIpattern\fR isn't specified, returns a list of names of all the
 307 subkeys of \fIkeyName\fR.  If \fIpattern\fR is specified, only those
 308 names matching \fIpattern\fR are returned.  Matching is determined
 309 using the same rules as for \fBstring\fR \fBmatch\fR.  If the
 310 specified \fIkeyName\fR does not exist, then an error is generated.
 311 .TP
 312 \fBregistry set \fIkeyName\fR ?\fIvalueName data \fR?\fItype\fR??
 313 .
 314 If \fIvalueName\fR isn't specified, creates the key \fIkeyName\fR if
 315 it doesn't already exist.  If \fIvalueName\fR is specified, creates
 316 the key \fIkeyName\fR and value \fIvalueName\fR if necessary.  The
 317 contents of \fIvalueName\fR are set to \fIdata\fR with the type
 318 indicated by \fItype\fR.  If \fItype\fR isn't specified, the type
 319 \fBsz\fR is assumed.  For more details on the data and type arguments,
 320 see SUPPORTED TYPES below.
 321 .TP
 322 \fBregistry type \fIkeyName valueName\fR
 323 .
 324 Returns the type of the value \fIvalueName\fR in the key
 325 \fIkeyName\fR.  For more information on the possible types, see
 326 SUPPORTED TYPES, below.
 327 .TP
 328 \fBregistry values \fIkeyName\fR ?\fIpattern\fR?
 329 .
 330 If \fIpattern\fR isn't specified, returns a list of names of all the
 331 values of \fIkeyName\fR.  If \fIpattern\fR is specified, only those
 332 names matching \fIpattern\fR are returned.  Matching is determined
 333 using the same rules as for \fBstring\fR \fBmatch\fR.
 334
 335 .SH "SUPPORTED TYPES"
 336 Each value under a key in the registry contains some data of a
 337 particular type in a type-specific representation.  The \fBregistry\fR
 338 command converts between this internal representation and one that can
 339 be manipulated by Tcl scripts.  In most cases, the data is simply
 340 returned as a Tcl string.  The type indicates the intended use for the
 341 data, but does not actually change the representation.  For some
 342 types, the \fBregistry\fR command returns the data in a different form to
 343 make it easier to manipulate.  The following types are recognized by the
 344 registry command:
 345 .TP 17
 346 \fBbinary\fR
 347 .
 348 The registry value contains arbitrary binary data.  The data is represented
 349 exactly in Tcl, including any embedded nulls.
 350 .TP
 351 \fBnone\fR
 352 .
 353 The registry value contains arbitrary binary data with no defined
 354 type.  The data is represented exactly in Tcl, including any embedded
 355 nulls.
 356 .TP
 357 \fBsz\fR
 358 .
 359 The registry value contains a null-terminated string.  The data is
 360 represented in Tcl as a string.
 361 .TP
 362 \fBexpand_sz\fR
 363 .
 364 The registry value contains a null-terminated string that contains
 365 unexpanded references to environment variables in the normal Windows
 366 style (for example, "%PATH%").  The data is represented in Tcl as a
 367 string.
 368 .TP
 369 \fBdword\fR
 370 .
 371 The registry value contains a little-endian 32-bit number.  The data is
 372 represented in Tcl as a decimal string.
 373 .TP
 374 \fBdword_big_endian\fR
 375 .
 376 The registry value contains a big-endian 32-bit number.  The data is
 377 represented in Tcl as a decimal string.
 378 .TP
 379 \fBlink\fR
 380 .
 381 The registry value contains a symbolic link.  The data is represented
 382 exactly in Tcl, including any embedded nulls.
 383 .TP
 384 \fBmulti_sz\fR
 385 .
 386 The registry value contains an array of null-terminated strings.  The
 387 data is represented in Tcl as a list of strings.
 388 .TP
 389 \fBresource_list\fR
 390 .
 391 The registry value contains a device-driver resource list.  The data
 392 is represented exactly in Tcl, including any embedded nulls.
 393 .PP
 394 In addition to the symbolically named types listed above, unknown
 395 types are identified using a 32-bit integer that corresponds to the
 396 type code returned by the system interfaces.  In this case, the data
 397 is represented exactly in Tcl, including any embedded nulls.
 398
 399 .SH "PORTABILITY ISSUES"
 400 The registry command is only available on Windows.
 401
 402 .SH KEYWORDS
 403 registry