CentOS 7.0 - man page for tcl_setbooleanobj (centos section 3)

Tcl_BooleanObj(3)				Tcl Library Procedures				    Tcl_BooleanObj(3)

_____________________________________________________________________________________________________________________

NAME
       Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj - store/retrieve boolean value in a Tcl_Obj

SYNOPSIS
       #include <tcl.h>

       Tcl_Obj *
       Tcl_NewBooleanObj(boolValue)

       Tcl_SetBooleanObj(objPtr, boolValue)

       int
       Tcl_GetBooleanFromObj(interp, objPtr, boolPtr)

ARGUMENTS
       int boolValue (in)		  Integer value to be stored as a boolean value in a Tcl_Obj.

       Tcl_Obj *objPtr (in/out) 	  Points  to the Tcl_Obj in which to store, or from which to retrieve a bool-
					  ean value.

       Tcl_Interp *interp (in/out)	  If a boolean value cannot be retrieved, an error message  is	left  in  the
					  interpreter's result object unless interp is NULL.

       int *boolPtr (out)		  Points  to place where Tcl_GetBooleanFromObj stores the boolean value (0 or
					  1) obtained from objPtr.
_________________________________________________________________

DESCRIPTION
       These procedures are used to pass boolean values to and from Tcl as Tcl_Obj's.  When storing a  boolean	value
       into  a	Tcl_Obj,  any non-zero integer value in boolValue is taken to be the boolean value 1, and the integer
       value 0 is taken to be the boolean value 0.

       Tcl_NewBooleanObj creates a new Tcl_Obj, stores the boolean value boolValue in it, and returns  a  pointer  to
       the new Tcl_Obj.  The new Tcl_Obj has reference count of zero.

       Tcl_SetBooleanObj  accepts  objPtr,  a  pointer	to an existing Tcl_Obj, and stores in the Tcl_Obj *objPtr the
       boolean value boolValue.  This is a write operation on *objPtr, so objPtr must be unshared.  Attempts to write
       to  a shared Tcl_Obj will panic.  A successful write of boolValue into *objPtr implies the freeing of any for-
       mer value stored in *objPtr.

       Tcl_GetBooleanFromObj attempts to retrieve a boolean value from the value stored in *objPtr.  If objPtr	holds
       a string value recognized by Tcl_GetBoolean, then the recognized boolean value is written at the address given
       by boolPtr.  If objPtr holds any value recognized as a number by Tcl, then if that value is zero a 0 is	writ-
       ten  at	the  address  given  by  boolPtr and if that value is non-zero a 1 is written at the address given by
       boolPtr.  In all cases where a value is written at the address given by boolPtr, Tcl_GetBooleanFromObj returns
       TCL_OK.	 If  the value of objPtr does not meet any of the conditions above, then TCL_ERROR is returned and an
       error message is left in the interpreter's result unless interp is NULL.  Tcl_GetBooleanFromObj may also  make
       changes to the internal fields of *objPtr so that future calls to Tcl_GetBooleanFromObj on the same objPtr can
       be performed more efficiently.

       Note that the routines Tcl_GetBooleanFromObj and Tcl_GetBoolean are not functional equivalents.	 The  set  of
       values  for which Tcl_GetBooleanFromObj will return TCL_OK is strictly larger than the set of values for which
       Tcl_GetBoolean will do the same.  For example, the value "5" passed to Tcl_GetBooleanFromObj will  lead	to  a
       TCL_OK  return  (and  the  boolean  value  1),  while  the  same value passed to Tcl_GetBoolean will lead to a
       TCL_ERROR return.

SEE ALSO
       Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean

KEYWORDS
       boolean, object

Tcl							 8.5					    Tcl_BooleanObj(3)