OSDN Git Service

Please enter the commit message for your changes. Lines starting
[eos/hostdependX86LINUX64.git] / util / X86LINUX64 / man / man3 / Tcl_LinkVar.3
index 5ee95f3..a69f2a1 100644 (file)
@@ -5,76 +5,81 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: LinkVar.3,v 1.6.2.1 2003/07/18 16:56:24 dgp Exp $
-'\" 
-'\" The definitions below are for supplemental macros used in Tcl/Tk
-'\" manual entries.
-'\"
-'\" .AP type name in/out ?indent?
-'\"    Start paragraph describing an argument to a library procedure.
-'\"    type is type of argument (int, etc.), in/out is either "in", "out",
-'\"    or "in/out" to describe whether procedure reads or modifies arg,
-'\"    and indent is equivalent to second arg of .IP (shouldn't ever be
-'\"    needed;  use .AS below instead)
-'\"
-'\" .AS ?type? ?name?
-'\"    Give maximum sizes of arguments for setting tab stops.  Type and
-'\"    name are examples of largest possible arguments that will be passed
-'\"    to .AP later.  If args are omitted, default tab stops are used.
-'\"
-'\" .BS
-'\"    Start box enclosure.  From here until next .BE, everything will be
-'\"    enclosed in one large box.
-'\"
-'\" .BE
-'\"    End of box enclosure.
-'\"
-'\" .CS
-'\"    Begin code excerpt.
-'\"
-'\" .CE
-'\"    End code excerpt.
-'\"
-'\" .VS ?version? ?br?
-'\"    Begin vertical sidebar, for use in marking newly-changed parts
-'\"    of man pages.  The first argument is ignored and used for recording
-'\"    the version when the .VS was added, so that the sidebars can be
-'\"    found and removed when they reach a certain age.  If another argument
-'\"    is present, then a line break is forced before starting the sidebar.
-'\"
-'\" .VE
-'\"    End of vertical sidebar.
-'\"
-'\" .DS
-'\"    Begin an indented unfilled display.
-'\"
-'\" .DE
-'\"    End of indented unfilled display.
-'\"
-'\" .SO
-'\"    Start of list of standard options for a Tk widget.  The
-'\"    options follow on successive lines, in four columns separated
-'\"    by tabs.
-'\"
-'\" .SE
-'\"    End of list of standard options for a Tk widget.
-'\"
-'\" .OP cmdName dbName dbClass
-'\"    Start of description of a specific option.  cmdName gives the
-'\"    option's name as specified in the class command, dbName gives
-'\"    the option's name in the option database, and dbClass gives
-'\"    the option's class in the option database.
-'\"
-'\" .UL arg1 arg2
-'\"    Print arg1 underlined, then print arg2 normally.
-'\"
-'\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
-'\"
-'\"    # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
+.TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
+.\" The -*- nroff -*- definitions below are for supplemental macros used
+.\" in Tcl/Tk manual entries.
+.\"
+.\" .AP type name in/out ?indent?
+.\"    Start paragraph describing an argument to a library procedure.
+.\"    type is type of argument (int, etc.), in/out is either "in", "out",
+.\"    or "in/out" to describe whether procedure reads or modifies arg,
+.\"    and indent is equivalent to second arg of .IP (shouldn't ever be
+.\"    needed;  use .AS below instead)
+.\"
+.\" .AS ?type? ?name?
+.\"    Give maximum sizes of arguments for setting tab stops.  Type and
+.\"    name are examples of largest possible arguments that will be passed
+.\"    to .AP later.  If args are omitted, default tab stops are used.
+.\"
+.\" .BS
+.\"    Start box enclosure.  From here until next .BE, everything will be
+.\"    enclosed in one large box.
+.\"
+.\" .BE
+.\"    End of box enclosure.
+.\"
+.\" .CS
+.\"    Begin code excerpt.
+.\"
+.\" .CE
+.\"    End code excerpt.
+.\"
+.\" .VS ?version? ?br?
+.\"    Begin vertical sidebar, for use in marking newly-changed parts
+.\"    of man pages.  The first argument is ignored and used for recording
+.\"    the version when the .VS was added, so that the sidebars can be
+.\"    found and removed when they reach a certain age.  If another argument
+.\"    is present, then a line break is forced before starting the sidebar.
+.\"
+.\" .VE
+.\"    End of vertical sidebar.
+.\"
+.\" .DS
+.\"    Begin an indented unfilled display.
+.\"
+.\" .DE
+.\"    End of indented unfilled display.
+.\"
+.\" .SO ?manpage?
+.\"    Start of list of standard options for a Tk widget. The manpage
+.\"    argument defines where to look up the standard options; if
+.\"    omitted, defaults to "options". The options follow on successive
+.\"    lines, in three columns separated by tabs.
+.\"
+.\" .SE
+.\"    End of list of standard options for a Tk widget.
+.\"
+.\" .OP cmdName dbName dbClass
+.\"    Start of description of a specific option.  cmdName gives the
+.\"    option's name as specified in the class command, dbName gives
+.\"    the option's name in the option database, and dbClass gives
+.\"    the option's class in the option database.
+.\"
+.\" .UL arg1 arg2
+.\"    Print arg1 underlined, then print arg2 normally.
+.\"
+.\" .QW arg1 ?arg2?
+.\"    Print arg1 in quotes, then arg2 normally (for trailing punctuation).
+.\"
+.\" .PQ arg1 ?arg2?
+.\"    Print an open parenthesis, arg1 in quotes, then arg2 normally
+.\"    (for trailing punctuation) and then a closing parenthesis.
+.\"
+.\"    # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
 .if t .wh -1.3i ^B
 .nr ^l \n(.l
 .ad b
-'\"    # Start an argument description
+.\"    # Start an argument description
 .de AP
 .ie !"\\$4"" .TP \\$4
 .el \{\
@@ -83,7 +88,7 @@
 .\}
 .ta \\n()Au \\n()Bu
 .ie !"\\$3"" \{\
-\&\\$1 \\fI\\$2\\fP    (\\$3)
+\&\\$1 \\fI\\$2\\fP (\\$3)
 .\".b
 .\}
 .el \{\
 .\}
 .\}
 ..
-'\"    # define tabbing values for .AP
+.\"    # define tabbing values for .AP
 .de AS
 .nr )A 10n
 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 ..
 .AS Tcl_Interp Tcl_CreateInterp in/out
-'\"    # BS - start boxed text
-'\"    # ^y = starting y location
-'\"    # ^b = 1
+.\"    # BS - start boxed text
+.\"    # ^y = starting y location
+.\"    # ^b = 1
 .de BS
 .br
 .mk ^y
 .if n \l'\\n(.lu\(ul'
 .if n .fi
 ..
-'\"    # BE - end boxed text (draw box now)
+.\"    # BE - end boxed text (draw box now)
 .de BE
 .nf
 .ti 0
 .br
 .nr ^b 0
 ..
-'\"    # VS - start vertical sidebar
-'\"    # ^Y = starting y location
-'\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
+.\"    # VS - start vertical sidebar
+.\"    # ^Y = starting y location
+.\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
 .de VS
 .if !"\\$2"" .br
 .mk ^Y
 .ie n 'mc \s12\(br\s0
 .el .nr ^v 1u
 ..
-'\"    # VE - end of vertical sidebar
+.\"    # VE - end of vertical sidebar
 .de VE
 .ie n 'mc
 .el \{\
 .\}
 .nr ^v 0
 ..
-'\"    # Special macro to handle page bottom:  finish off current
-'\"    # box/sidebar if in box/sidebar mode, then invoked standard
-'\"    # page bottom macro.
+.\"    # Special macro to handle page bottom:  finish off current
+.\"    # box/sidebar if in box/sidebar mode, then invoked standard
+.\"    # page bottom macro.
 .de ^B
 .ev 2
 'ti 0
 .mk ^Y
 .\}
 ..
-'\"    # DS - begin display
+.\"    # DS - begin display
 .de DS
 .RS
 .nf
 .sp
 ..
-'\"    # DE - end display
+.\"    # DE - end display
 .de DE
 .fi
 .RE
 .sp
 ..
-'\"    # SO - start of list of standard options
+.\"    # SO - start of list of standard options
 .de SO
+'ie '\\$1'' .ds So \\fBoptions\\fR
+'el .ds So \\fB\\$1\\fR
 .SH "STANDARD OPTIONS"
 .LP
 .nf
 .ta 5.5c 11c
 .ft B
 ..
-'\"    # SE - end of list of standard options
+.\"    # SE - end of list of standard options
 .de SE
 .fi
 .ft R
 .LP
-See the \\fBoptions\\fR manual entry for details on the standard options.
+See the \\*(So manual entry for details on the standard options.
 ..
-'\"    # OP - start of full description for a single option
+.\"    # OP - start of full description for a single option
 .de OP
 .LP
 .nf
@@ -229,21 +236,43 @@ Database Class:   \\fB\\$3\\fR
 .fi
 .IP
 ..
-'\"    # CS - begin code excerpt
+.\"    # CS - begin code excerpt
 .de CS
 .RS
 .nf
 .ta .25i .5i .75i 1i
 ..
-'\"    # CE - end code excerpt
+.\"    # CE - end code excerpt
 .de CE
 .fi
 .RE
 ..
+.\"    # UL - underline word
 .de UL
 \\$1\l'|0\(ul'\\$2
 ..
-.TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
+.\"    # QW - apply quotation marks to word
+.de QW
+.ie '\\*(lq'"' ``\\$1''\\$2
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\$2
+..
+.\"    # PQ - apply parens and quotation marks to word
+.de PQ
+.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
+.\"" fix emacs highlighting
+.el (\\*(lq\\$1\\*(rq\\$2)\\$3
+..
+.\"    # QR - quoted range
+.de QR
+.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
+..
+.\"    # MT - "empty" string
+.de MT
+.QW ""
+..
 .BS
 .SH NAME
 Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
@@ -262,19 +291,20 @@ int
 .AP Tcl_Interp *interp in
 Interpreter that contains \fIvarName\fR.
 Also used by \fBTcl_LinkVar\fR to return error messages.
-.AP "CONST char" *varName in
-Name of global variable.  
+.AP "const char" *varName in
+Name of global variable.
 .AP char *addr in
 Address of C variable that is to be linked to \fIvarName\fR.
 .AP int type in
-Type of C variable.  Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE,
-.VS 8.4
-TCL_LINK_WIDE_INT,
-.VE 8.4
-TCL_LINK_BOOLEAN, or TCL_LINK_STRING, optionally OR'ed with
-TCL_LINK_READ_ONLY to make Tcl variable read-only.
+Type of C variable.  Must be one of \fBTCL_LINK_INT\fR,
+\fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR,
+\fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR,
+\fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR,
+\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR,
+\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or
+\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR
+to make Tcl variable read-only.
 .BE
-
 .SH DESCRIPTION
 .PP
 \fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable
@@ -283,14 +313,14 @@ given by \fIaddr\fR.
 Whenever the Tcl variable is read the value of the C variable will
 be returned, and whenever the Tcl variable is written the C
 variable will be updated to have the same value.
-\fBTcl_LinkVar\fR normally returns TCL_OK;  if an error occurs
+\fBTcl_LinkVar\fR normally returns \fBTCL_OK\fR;  if an error occurs
 while setting up the link (e.g. because \fIvarName\fR is the
-name of array) then TCL_ERROR is returned and the interpreter's result
+name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result
 contains an error message.
 .PP
 The \fItype\fR argument specifies the type of the C variable,
 and must have one of the following values, optionally OR'ed with
-TCL_LINK_READ_ONLY:
+\fBTCL_LINK_READ_ONLY\fR:
 .TP
 \fBTCL_LINK_INT\fR
 The C variable is of type \fBint\fR.
@@ -299,6 +329,59 @@ form acceptable to \fBTcl_GetIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors.
 .TP
+\fBTCL_LINK_UINT\fR
+The C variable is of type \fBunsigned int\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
+platform's defined range for the \fBunsigned int\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_CHAR\fR
+The C variable is of type \fBchar\fR.
+Any value written into the Tcl variable must have a proper integer
+form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
+\fBchar\fR datatype; attempts to write non-integer or out-of-range
+values into \fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_UCHAR\fR
+The C variable is of type \fBunsigned char\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
+platform's defined range for the \fBunsigned char\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_SHORT\fR
+The C variable is of type \fBshort\fR.
+Any value written into the Tcl variable must have a proper integer
+form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
+\fBshort\fR datatype; attempts to write non-integer or out-of-range
+values into \fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_USHORT\fR
+The C variable is of type \fBunsigned short\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
+platform's defined range for the \fBunsigned short\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_LONG\fR
+The C variable is of type \fBlong\fR.
+Any value written into the Tcl variable must have a proper integer
+form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write
+non-integer or out-of-range
+values into \fIvarName\fR will be rejected with Tcl errors.
+.TP
+\fBTCL_LINK_ULONG\fR
+The C variable is of type \fBunsigned long\fR.
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
+platform's defined range for the \fBunsigned long\fR type; attempts to
+write non-integer values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
 \fBTCL_LINK_DOUBLE\fR
 The C variable is of type \fBdouble\fR.
 Any value written into the Tcl variable must have a proper real
@@ -306,20 +389,39 @@ form acceptable to \fBTcl_GetDoubleFromObj\fR;  attempts to write
 non-real values into \fIvarName\fR will be rejected with
 Tcl errors.
 .TP
+\fBTCL_LINK_FLOAT\fR
+The C variable is of type \fBfloat\fR.
+Any value written into the Tcl variable must have a proper real
+form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the
+range acceptable for a \fBfloat\fR; attempts to
+write non-real values (or values outside the range) into
+\fIvarName\fR will be rejected with Tcl errors.
+.TP
 \fBTCL_LINK_WIDE_INT\fR
-.VS 8.4
 The C variable is of type \fBTcl_WideInt\fR (which is an integer type
 at least 64-bits wide on all platforms that can support it.)
 Any value written into the Tcl variable must have a proper integer
 form acceptable to \fBTcl_GetWideIntFromObj\fR;  attempts to write
 non-integer values into \fIvarName\fR will be rejected with
 Tcl errors.
-.VE 8.4
+.TP
+\fBTCL_LINK_WIDE_UINT\fR
+The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned
+integer type at least 64-bits wide on all platforms that can support
+it.)
+Any value written into the Tcl variable must have a proper unsigned
+integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be
+cast to unsigned);
+.\" FIXME! Use bignums instead.
+attempts to write non-integer values into \fIvarName\fR will be
+rejected with Tcl errors.
 .TP
 \fBTCL_LINK_BOOLEAN\fR
 The C variable is of type \fBint\fR.
-If its value is zero then it will read from Tcl as ``0'';
-otherwise it will read from Tcl as ``1''.
+If its value is zero then it will read from Tcl as
+.QW 0 ;
+otherwise it will read from Tcl as
+.QW 1 .
 Whenever \fIvarName\fR is
 modified, the C variable will be set to a 0 or 1 value.
 Any value written into the Tcl variable must have a proper boolean
@@ -329,17 +431,16 @@ Tcl errors.
 .TP
 \fBTCL_LINK_STRING\fR
 The C variable is of type \fBchar *\fR.
-.VS
 If its value is not NULL then it must be a pointer to a string
 allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
-.VE
 Whenever the Tcl variable is modified the current C string will be
 freed and new memory will be allocated to hold a copy of the variable's
 new value.
 If the C variable contains a NULL pointer then the Tcl variable
-will read as ``NULL''.
+will read as
+.QW NULL .
 .PP
-If the TCL_LINK_READ_ONLY flag is present in \fItype\fR then the
+If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
 variable will be read-only from Tcl, so that its value can only be
 changed by modifying the C variable.
 Attempts to write the variable from Tcl will be rejected with errors.
@@ -357,6 +458,16 @@ Tk widget that wishes to display the value of the variable), the
 trace will not trigger when the C variable has changed.
 \fBTcl_UpdateLinkedVar\fR ensures that any traces on the Tcl
 variable are invoked.
-
+.PP
+Note that, as with any call to a Tcl interpreter, \fBTcl_UpdateLinkedVar\fR
+must be called from the same thread that created the interpreter. The safest
+mechanism is to ensure that the C variable is only ever updated from the same
+thread that created the interpreter (possibly in response to an event posted
+with \fBTcl_ThreadQueueEvent\fR), but when it is necessary to update the
+variable in a separate thread, it is advised that \fBTcl_AsyncMark\fR be used
+to indicate to the thread hosting the interpreter that it is ready to run
+\fBTcl_UpdateLinkedVar\fR.
+.SH "SEE ALSO"
+Tcl_TraceVar(3)
 .SH KEYWORDS
-boolean, integer, link, read-only, real, string, traces, variable
+boolean, integer, link, read-only, real, string, trace, variable