diff options
Diffstat (limited to 'doc/registry.n')
| -rw-r--r-- | doc/registry.n | 103 |
1 files changed, 76 insertions, 27 deletions
diff --git a/doc/registry.n b/doc/registry.n index 4b7dbf3..001def9 100644 --- a/doc/registry.n +++ b/doc/registry.n @@ -1,24 +1,22 @@ '\" '\" Copyright (c) 1997 Sun Microsystems, Inc. +'\" Copyright (c) 2002 ActiveState Corporation. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: registry.n,v 1.3 1999/02/02 22:25:21 stanton Exp $ -'\" +.TH registry n 1.1 registry "Tcl Bundled Packages" .so man.macros -.TH registry n 8.0 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME registry \- Manipulate the Windows registry .SH SYNOPSIS .sp -\fBpackage require registry 1.0\fR +\fBpackage require registry 1.3\fR .sp -\fBregistry \fIoption\fR \fIkeyName\fR ?\fIarg arg ...\fR? +\fBregistry \fR?\fI\-mode\fR? \fIoption\fR \fIkeyName\fR ?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP The \fBregistry\fR package provides a general set of operations for @@ -29,33 +27,67 @@ as a corrupted registry can leave your system in an unusable state. .PP \fIKeyName\fR is the name of a registry key. Registry keys must be one of the following forms: -.IP +.RS +.PP \fB\e\e\fIhostname\fB\e\fIrootname\fB\e\fIkeypath\fR -.IP +.PP \fIrootname\fB\e\fIkeypath\fR -.IP +.PP \fIrootname\fR +.RE .PP \fIHostname\fR specifies the name of any valid Windows host that exports its registry. The \fIrootname\fR component must be one of \fBHKEY_LOCAL_MACHINE\fR, \fBHKEY_USERS\fR, -.VS \fBHKEY_CLASSES_ROOT\fR, \fBHKEY_CURRENT_USER\fR, \fBHKEY_CURRENT_CONFIG\fR, \fBHKEY_PERFORMANCE_DATA\fR, or \fBHKEY_DYN_DATA\fR. The \fIkeypath\fR can be one or more -.VE registry key names separated by backslash (\fB\e\fR) characters. .PP +.VS 8.6 +The optional \fI\-mode\fR argument indicates which registry to work +with; when it is \fB\-32bit\fR the 32-bit registry will be used, and +when it is \fB\-64bit\fR the 64-bit registry will be used. If this +argument is omitted, the system's default registry will be the subject +of the requested operation. +.VE 8.6 +.PP \fIOption\fR indicates what to do with the registry key name. Any unique abbreviation for \fIoption\fR is acceptable. The valid options are: .TP +\fBregistry broadcast \fIkeyName\fR ?\fB\-timeout \fImilliseconds\fR? +. +Sends a broadcast message to the system and running programs to notify them +of certain updates. This is necessary to propagate changes to key registry +keys like Environment. The timeout specifies the amount of time, in +milliseconds, to wait for applications to respond to the broadcast message. +It defaults to 3000. The following example demonstrates how to add a path +to the global Environment and notify applications of the change without +requiring a logoff/logon step (assumes admin privileges): +.RS +.PP +.CS +set regPath [join { + HKEY_LOCAL_MACHINE + SYSTEM + CurrentControlSet + Control + {Session Manager} + Environment +} "\e\e"] +set curPath [\fBregistry get\fR $regPath "Path"] +\fBregistry set\fR $regPath "Path" "$curPath;$addPath" +\fBregistry broadcast\fR "Environment" +.CE +.RE +.TP \fBregistry delete \fIkeyName\fR ?\fIvalueName\fR? . If the optional \fIvalueName\fR argument is present, the specified value under \fIkeyName\fR will be deleted from the registry. If the optional \fIvalueName\fR is omitted, the specified key and any subkeys -or values beneath it in the registry heirarchy will be deleted. If +or values beneath it in the registry hierarchy will be deleted. If the key could not be deleted then an error is generated. If the key did not exist, the command has no effect. .TP @@ -64,39 +96,38 @@ did not exist, the command has no effect. Returns the data associated with the value \fIvalueName\fR under the key \fIkeyName\fR. If either the key or the value does not exist, then an error is generated. For more details on the format of the returned -data, see SUPPORTED TYPES, below. +data, see \fBSUPPORTED TYPES\fR, below. .TP \fBregistry keys \fIkeyName\fR ?\fIpattern\fR? . -If \fIpattern\fR isn't specified, returns a list of names of all the +If \fIpattern\fR is not specified, returns a list of names of all the subkeys of \fIkeyName\fR. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined -using the same rules as for \fBstring\fR \fBmatch\fR. If the +using the same rules as for \fBstring match\fR. If the specified \fIkeyName\fR does not exist, then an error is generated. .TP \fBregistry set \fIkeyName\fR ?\fIvalueName data \fR?\fItype\fR?? . -If \fIvalueName\fR isn't specified, creates the key \fIkeyName\fR if -it doesn't already exist. If \fIvalueName\fR is specified, creates +If \fIvalueName\fR is not specified, creates the key \fIkeyName\fR if +it does not already exist. If \fIvalueName\fR is specified, creates the key \fIkeyName\fR and value \fIvalueName\fR if necessary. The contents of \fIvalueName\fR are set to \fIdata\fR with the type -indicated by \fItype\fR. If \fItype\fR isn't specified, the type +indicated by \fItype\fR. If \fItype\fR is not specified, the type \fBsz\fR is assumed. For more details on the data and type arguments, -see SUPPORTED TYPES below. +see \fBSUPPORTED TYPES\fR below. .TP \fBregistry type \fIkeyName valueName\fR . Returns the type of the value \fIvalueName\fR in the key \fIkeyName\fR. For more information on the possible types, see -SUPPORTED TYPES, below. +\fBSUPPORTED TYPES\fR, below. .TP \fBregistry values \fIkeyName\fR ?\fIpattern\fR? . -If \fIpattern\fR isn't specified, returns a list of names of all the +If \fIpattern\fR is not specified, returns a list of names of all the values of \fIkeyName\fR. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined -using the same rules as for \fBstring\fR \fBmatch\fR. - +using the same rules as for \fBstring match\fR. .SH "SUPPORTED TYPES" Each value under a key in the registry contains some data of a particular type in a type-specific representation. The \fBregistry\fR @@ -112,7 +143,6 @@ registry command: . The registry value contains arbitrary binary data. The data is represented exactly in Tcl, including any embedded nulls. -Tcl .TP \fBnone\fR . @@ -129,8 +159,9 @@ represented in Tcl as a string. . The registry value contains a null-terminated string that contains unexpanded references to environment variables in the normal Windows -style (for example, "%PATH%"). The data is represented in Tcl as a -string. +style (for example, +.QW %PATH% ). +The data is represented in Tcl as a string. .TP \fBdword\fR . @@ -161,9 +192,27 @@ In addition to the symbolically named types listed above, unknown types are identified using a 32-bit integer that corresponds to the type code returned by the system interfaces. In this case, the data is represented exactly in Tcl, including any embedded nulls. - .SH "PORTABILITY ISSUES" The registry command is only available on Windows. +.SH EXAMPLE +Print out how double-clicking on a Tcl script file will invoke a Tcl +interpreter: +.PP +.CS +package require registry +set ext .tcl + +# Read the type name +set type [\fBregistry get\fR HKEY_CLASSES_ROOT\e\e$ext {}] +# Work out where to look for the command +set path HKEY_CLASSES_ROOT\e\e$type\e\eShell\e\eOpen\e\ecommand +# Read the command! +set command [\fBregistry get\fR $path {}] +puts "$ext opens with $command" +.CE .SH KEYWORDS registry +'\" Local Variables: +'\" mode: nroff +'\" End: |