Manual Pages for UNIX Operating System command usage for man Tcl_LinkVar

Tcl Library Procedures                          Tcl_LinkVar(3TCL)



_________________________________________________________________

NAME
     Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar -  link  Tcl
     variable to C variable

SYNOPSIS
     #include 

     int
     Tcl_LinkVar(interp, varName, addr, type)

     Tcl_UnlinkVar(interp, varName)

     Tcl_UpdateLinkedVar(interp, varName)

ARGUMENTS
     Tcl_Interp   *interp    (in)      Interpreter that  contains
                                       varName.    Also  used  by
                                       Tcl_LinkVar   to    return
                                       error messages.

     CONST char   *varName   (in)      Name of global variable.

     char         *addr      (in)      Address of C variable that
                                       is  to  be  linked to var-
                                       Name.

     int          type       (in)      Type of C variable.   Must
                                       be  one  of  TCL_LINK_INT,
                                       TCL_LINK_DOUBLE,  |
                                       TCL_LINK_WIDE_INT,
                                       TCL_LINK_BOOLEAN,       or
                                       TCL_LINK_STRING,   option-
                                       ally      OR'ed       with
                                       TCL_LINK_READ_ONLY to make
                                       Tcl variable read-only.
_________________________________________________________________


DESCRIPTION
     Tcl_LinkVar uses variable traces to keep  the  Tcl  variable
     named  by varName in sync with the C variable at the address
     given by addr.  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.  Tcl_LinkVar normally returns TCL_OK;  if an
     error occurs while setting up the link (e.g. because varName
     is  the  name  of  array) then TCL_ERROR is returned and the
     interpreter's result contains an error message.





Tcl                     Last change: 7.5                        1






Tcl Library Procedures                          Tcl_LinkVar(3TCL)



     The type argument specifies the type of the C variable,  and
     must have one of the following values, optionally OR'ed with
     TCL_LINK_READ_ONLY:

     TCL_LINK_INT
          The C variable is of type int.  Any value written  into
          the  Tcl  variable  must  have  a  proper  integer form
          acceptable to  Tcl_GetIntFromObj;   attempts  to  write
          non-integer  values  into varName will be rejected with
          Tcl errors.

     TCL_LINK_DOUBLE
          The C variable is of type double.   Any  value  written
          into  the  Tcl  variable  must  have a proper real form
          acceptable to Tcl_GetDoubleFromObj;  attempts to  write
          non-real  values into varName will be rejected with Tcl
          errors.

     TCL_LINK_WIDE_INT
          The C variable is of  type  Tcl_WideInt  (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  |
          Tcl_GetWideIntFromObj;  attempts to  write  non-integer  |
          values into varName will be rejected with Tcl errors.

     TCL_LINK_BOOLEAN
          The C variable is of type int.  If its  value  is  zero
          then  it will read from Tcl as ``0''; otherwise it will
          read from Tcl as ``1''.  Whenever varName 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   form   acceptable  to  Tcl_GetBooleanFromObj;
          attempts to write non-boolean values into varName  will
          be rejected with Tcl errors.

     TCL_LINK_STRING
          The C variable is of type char *.  If its value is  not  |
          NULL  then  it  must be a pointer to a string allocated  |
          with Tcl_Alloc or ckalloc.  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''.

     If the TCL_LINK_READ_ONLY flag is present in type  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.





Tcl                     Last change: 7.5                        2






Tcl Library Procedures                          Tcl_LinkVar(3TCL)



     Tcl_UnlinkVar removes the link previously  set  up  for  the
     variable  given  by varName.  If there does not exist a link
     for varName then the procedure has no effect.

     Tcl_UpdateLinkedVar may be invoked after the C variable  has
     changed to force the Tcl variable to be updated immediately.
     In many cases  this  procedure  is  not  needed,  since  any
     attempt  to  read  the  Tcl  variable will return the latest
     value of the C variable.  However, if a trace has  been  set
     on  the  Tcl  variable  (such  as a Tk widget that wishes to
     display the value of  the  variable),  the  trace  will  not
     trigger     when     the    C    variable    has    changed.
     Tcl_UpdateLinkedVar ensures that any traces on the Tcl vari-
     able are invoked.


KEYWORDS
     boolean, integer, link,  read-only,  real,  string,  traces,
     variable

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.





















Tcl                     Last change: 7.5                        3