Пакет: tcl-devel

Tcl_SetRecursionLimit(3)    Tcl Library Procedures    Tcl_SetRecursionLimit(3)



______________________________________________________________________________

NAME
       Tcl_SetRecursionLimit  -	 set maximum allowable nesting depth in inter‐
       preter

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_SetRecursionLimit(interp, depth)

ARGUMENTS
       Tcl_Interp *interp (in)		Interpreter whose recursion  limit  is
					to be set.  Must be greater than zero.

       int depth (in)			New limit for nested calls to Tcl_Eval
					for interp.
______________________________________________________________________________


DESCRIPTION
       At any given time Tcl enforces a limit on the number of recursive calls
       that  may  be  active  for  Tcl_Eval  and  related  procedures  such as
       Tcl_GlobalEval.	Any call  to  Tcl_Eval	that  exceeds  this  depth  is
       aborted with an error.  By default the recursion limit is 1000.

       Tcl_SetRecursionLimit may be used to change the maximum allowable nest‐
       ing depth for an interpreter.  The depth argument specifies a new limit
       for  interp,  and Tcl_SetRecursionLimit returns the old limit.  To read
       out the old limit without modifying  it,	 invoke	 Tcl_SetRecursionLimit
       with depth equal to 0.

       The Tcl_SetRecursionLimit only sets the size of the Tcl call stack:  it
       cannot by itself prevent stack overflows on the C stack being  used  by
       the  application.   If  your  machine  has a limit on the size of the C
       stack, you may get stack overflows before reaching  the	limit  set  by
       Tcl_SetRecursionLimit.  If this happens, see if there is a mechanism in
       your system for increasing the maximum size of the C stack.


KEYWORDS
       nesting depth, recursion



Tcl				      7.0	      Tcl_SetRecursionLimit(3)

Tcl_Method(3)		    TclOO Library Functions		 Tcl_Method(3)



______________________________________________________________________________

NAME
       Tcl_ClassSetConstructor,	   Tcl_ClassSetDestructor,   Tcl_MethodDeclar‐
       erClass,	 Tcl_MethodDeclarerObject,  Tcl_MethodIsPublic,	 Tcl_MethodIs‐
       Type, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_Object‐
       ContextInvokeNext,     Tcl_ObjectContextIsFiltering,	Tcl_ObjectCon‐
       textMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs - ma‐
       nipulate methods and method-call contexts

SYNOPSIS
       #include <tclOO.h>

       Tcl_Method
       Tcl_NewMethod(interp, class, nameObj, isPublic,
		     methodTypePtr, clientData)

       Tcl_Method
       Tcl_NewInstanceMethod(interp, object, nameObj, isPublic,
			     methodTypePtr, clientData)

       Tcl_ClassSetConstructor(interp, class, method)

       Tcl_ClassSetDestructor(interp, class, method)

       Tcl_Class
       Tcl_MethodDeclarerClass(method)

       Tcl_Object
       Tcl_MethodDeclarerObject(method)

       Tcl_Obj *
       Tcl_MethodName(method)

       int
       Tcl_MethodIsPublic(method)

       int
       Tcl_MethodIsType(method, methodTypePtr, clientDataPtr)

       int
       Tcl_ObjectContextInvokeNext(interp, context, objc, objv, skip)

       int
       Tcl_ObjectContextIsFiltering(context)

       Tcl_Method
       Tcl_ObjectContextMethod(context)

       Tcl_Object
       Tcl_ObjectContextObject(context)

       int
       Tcl_ObjectContextSkippedArgs(context)

ARGUMENTS
       Tcl_Interp *interp (in/out)	   The interpreter holding the	object
					   or  class  to  create  or  update a
					   method in.

       Tcl_Object object (in)		   The object to create the method in.

       Tcl_Class class (in)		   The class to create the method in.

       Tcl_Obj *nameObj (in)		   The name of the method  to  create.
					   Should  not be NULL unless creating
					   constructors or destructors.

       int isPublic (in)		   A flag saying what  the  visibility
					   of  the  method  is.	 The only sup‐
					   ported public values of  this  flag
					   are	0  for	a non-exported method,
					   and 1 for an exported method.

       Tcl_MethodType *methodTypePtr (in)  A description of the	 type  of  the
					   method  to  create,	or the type of
					   method to compare against.

       ClientData clientData (in)	   A piece of data that is  passed  to
					   the	implementation	of  the method
					   without interpretation.

       ClientData *clientDataPtr (out)	   A pointer to a variable in which to
					   write the clientData value supplied
					   when the  method  was  created.  If
					   NULL, the clientData value will not
					   be retrieved.

       Tcl_Method method (in)		   A reference to a method to query.

       Tcl_ObjectContext context (in)	   A reference to a  method-call  con‐
					   text.  Note	that  client code must
					   not retain a reference  to  a  con‐
					   text.

       int objc (in)			   The	number of arguments to pass to
					   the method implementation.

       Tcl_Obj *const *objv (in)	   An array of arguments  to  pass  to
					   the method implementation.

       int skip (in)			   The	number	of arguments passed to
					   the method implementation  that  do
					   not represent "real" arguments.
______________________________________________________________________________

DESCRIPTION
       A  method  is  an operation carried out on an object that is associated
       with the object. Every method must be attached to either an object or a
       class;  methods	attached  to a class are associated with all instances
       (direct and indirect) of that class.

       Given a method,	the  entity  that  declared  it	 can  be  found	 using
       Tcl_MethodDeclarerClass	which returns the class that the method is at‐
       tached to (or NULL if the method is not	attached  to  any  class)  and
       Tcl_MethodDeclarerObject	 which	returns	 the object that the method is
       attached to (or NULL if the method is not attached to an	 object).  The
       name of the method can be retrieved with Tcl_MethodName and whether the
       method is exported is retrieved with Tcl_MethodIsPublic.	 The  type  of
       the method can also be introspected upon to a limited degree; the func‐
       tion Tcl_MethodIsType returns whether a method is of a particular type,
       assigning  the  per-method  clientData  to  the	variable pointed to by
       clientDataPtr if (that is non-NULL) if the type is matched.

   METHOD CREATION
       Methods are created by Tcl_NewMethod and	 Tcl_NewInstanceMethod,	 which
       create  a method attached to a class or an object respectively. In both
       cases, the nameObj argument gives the name of the method to create, the
       isPublic	 argument  states  whether  the method should be exported ini‐
       tially, the methodTypePtr argument describes the implementation of  the
       method (see the METHOD TYPES section below) and the clientData argument
       gives some implementation-specific data that is passed on to the imple‐
       mentation of the method when it is called.

       When  the  nameObj argument to Tcl_NewMethod is NULL, an unnamed method
       is created, which is used for constructors and destructors.   Construc‐
       tors  should  be	 installed into their class using the Tcl_ClassSetCon‐
       structor function, and destructors (which must not  require  any	 argu‐
       ments)  should  be installed into their class using the Tcl_ClassSetDe‐
       structor function. Unnamed methods should not be	 used  for  any	 other
       purpose, and named methods should not be used as either constructors or
       destructors. Also note that a NULL methodTypePtr is used to provide in‐
       ternal signaling, and should not be used in client code.

   METHOD CALL CONTEXTS
       When  a	method is called, a method-call context reference is passed in
       as one of the arguments to the implementation  function.	 This  context
       can  be	inspected  to provide information about the caller, but should
       not be retained beyond the moment when the method call terminates.

       The method that is being called can be retrieved from  the  context  by
       using Tcl_ObjectContextMethod, and the object that caused the method to
       be invoked can be retrieved with Tcl_ObjectContextObject. The number of
       arguments  that are to be skipped (e.g. the object name and method name
       in a normal method call) is read with Tcl_ObjectContextSkippedArgs, and
       the  context  can also report whether it is working as a filter for an‐
       other method through Tcl_ObjectContextIsFiltering.

       During the execution of a method, the method implementation may	choose
       to  invoke the stages of the method call chain that come after the cur‐
       rent method implementation. This (the core of the next command) is done
       using Tcl_ObjectContextInvokeNext. Note that this function does not ma‐
       nipulate the call-frame stack, unlike the next command; if  the	method
       implementation has pushed one or more extra frames on the stack as part
       of its implementation, it is also responsible for  temporarily  popping
       those frames from the stack while the Tcl_ObjectContextInvokeNext func‐
       tion is executing. Note also that  the  method-call  context  is	 never
       deleted during the execution of this function.

METHOD TYPES
       The  types  of  methods	are described by a pointer to a Tcl_MethodType
       structure, which is defined as:

	      typedef struct {
		  int version;
		  const char *name;
		  Tcl_MethodCallProc *callProc;
		  Tcl_MethodDeleteProc *deleteProc;
		  Tcl_CloneProc *cloneProc;
	      } Tcl_MethodType;

       The version field allows for future expansion  of  the  structure,  and
       should  always  be declared equal to TCL_OO_METHOD_VERSION_CURRENT. The
       name field provides a human-readable name for  the  type,  and  is  the
       value  that  is	exposed	 via the info class methodtype and info object
       methodtype Tcl commands.

       The callProc field gives a function that is called when the  method  is
       invoked; it must never be NULL.

       The deleteProc field gives a function that is used to delete a particu‐
       lar method, and is called when the method is replaced  or  removed;  if
       the  field is NULL, it is assumed that the method's clientData needs no
       special action to delete.

       The cloneProc field is either  a	 function  that	 is  used  to  copy  a
       method's	 clientData (as part of Tcl_CopyObjectInstance) or NULL to in‐
       dicate that the clientData can just be copied directly.

   TCL_METHODCALLPROC FUNCTION SIGNATURE
       Functions matching this signature are called when  the  method  is  in‐
       voked.

	      typedef int Tcl_MethodCallProc(
		      ClientData clientData,
		      Tcl_Interp *interp,
		      Tcl_ObjectContext objectContext,
		      int objc,
		      Tcl_Obj *const *objv);

       The  clientData	argument to a Tcl_MethodCallProc is the value that was
       given when the method was created, the interp is a place	 in  which  to
       execute	scripts and access variables as well as being where to put the
       result of the method, and the objc and objv fields give	the  parameter
       objects to the method. The calling context of the method can be discov‐
       ered through the objectContext argument, and the return	value  from  a
       Tcl_MethodCallProc is any Tcl return code (e.g. TCL_OK, TCL_ERROR).

   TCL_METHODDELETEPROC FUNCTION SIGNATURE
       Functions  matching  this  signature are used when a method is deleted,
       whether through a new method being created or  because  the  object  or
       class is deleted.

	      typedef void Tcl_MethodDeleteProc(
		      ClientData clientData);

       The  clientData	argument to a Tcl_MethodDeleteProc will be the same as
       the value  passed  to  the  clientData  argument	 to  Tcl_NewMethod  or
       Tcl_NewInstanceMethod when the method was created.

   TCL_CLONEPROC FUNCTION SIGNATURE
       Functions  matching  this  signature are used to copy a method when the
       object or class is copied using Tcl_CopyObjectInstance (or oo::copy).

	      typedef int Tcl_CloneProc(
		      Tcl_Interp *interp,
		      ClientData oldClientData,
		      ClientData *newClientDataPtr);

       The interp argument gives a place to write an error  message  when  the
       attempt	to clone the object is to fail, in which case the clone proce‐
       dure must also return TCL_ERROR; it  should  return  TCL_OK  otherwise.
       The  oldClientData  field  to  a Tcl_CloneProc gives the value from the
       method being copied from, and the newClientDataPtr field will point  to
       a variable in which to write the value for the method being copied to.

SEE ALSO
       Class(3), oo::class(n), oo::define(n), oo::object(n)

KEYWORDS
       constructor, method, object




TclOO				      0.1			 Tcl_Method(3)

Tcl_Namespace(3)	    Tcl Library Procedures	      Tcl_Namespace(3)



______________________________________________________________________________

NAME
       Tcl_AppendExportList, Tcl_CreateNamespace, Tcl_DeleteNamespace, Tcl_Ex‐
       port, Tcl_FindCommand, Tcl_FindNamespace, Tcl_ForgetImport, Tcl_GetCur‐
       rentNamespace,  Tcl_GetGlobalNamespace, Tcl_GetNamespaceUnknownHandler,
       Tcl_Import, Tcl_SetNamespaceUnknownHandler - manipulate namespaces

SYNOPSIS
       #include <tcl.h>

       Tcl_Namespace *
       Tcl_CreateNamespace(interp, name, clientData, deleteProc)

       Tcl_DeleteNamespace(nsPtr)

       int
       Tcl_AppendExportList(interp, nsPtr, objPtr)

       int
       Tcl_Export(interp, nsPtr, pattern, resetListFirst)

       int
       Tcl_Import(interp, nsPtr, pattern, allowOverwrite)

       int
       Tcl_ForgetImport(interp, nsPtr, pattern)

       Tcl_Namespace *
       Tcl_GetCurrentNamespace(interp)

       Tcl_Namespace *
       Tcl_GetGlobalNamespace(interp)

       Tcl_Namespace *
       Tcl_FindNamespace(interp, name, contextNsPtr, flags)

       Tcl_Command
       Tcl_FindCommand(interp, name, contextNsPtr, flags)

       Tcl_Obj *
       Tcl_GetNamespaceUnknownHandler(interp, nsPtr)

       int
       Tcl_SetNamespaceUnknownHandler(interp, nsPtr, handlerPtr)

ARGUMENTS
       Tcl_Interp *interp (in/out)			    The interpreter in
							    which   the	 name‐
							    space  exists  and
							    where name lookups
							    are	    performed.
							    Also  where	 error
							    result    messages
							    are written.

       const char *name (in)				    The	 name  of  the
							    namespace or  com‐
							    mand to be created
							    or accessed.

       ClientData clientData (in)			    A context  pointer
							    by	the creator of
							    the	    namespace.
							    Not interpreted by
							    Tcl at all.

       Tcl_NamespaceDeleteProc *deleteProc (in)		    A pointer to func‐
							    tion  to call when
							    the	 namespace  is
							    deleted,  or  NULL
							    if no  such	 call‐
							    back is to be per‐
							    formed.

       Tcl_Namespace *nsPtr (in)			    The	 namespace  to
							    be manipulated, or
							    NULL  (for	 other
							    than   Tcl_Delete‐
							    Namespace) to  ma‐
							    nipulate  the cur‐
							    rent namespace.

       Tcl_Obj *objPtr (out)				    A reference to  an
							    unshared  value to
							    which the function
							    output   will   be
							    written.

       const char *pattern (in)				    The	    glob-style
							    pattern	  (see
							    Tcl_StringMatch)
							    that describes the
							    commands to be im‐
							    ported    or   ex‐
							    ported.

       int resetListFirst (in)				    Whether  the  list
							    of export patterns
							    should  be	 reset
							    before  adding the
							    current pattern to
							    it.

       int allowOverwrite (in)				    Whether  new  com‐
							    mands  created  by
							    this import action
							    can overwrite  ex‐
							    isting commands.

       Tcl_Namespace *contextNsPtr (in)			    The	  location  in
							    the namespace  hi‐
							    erarchy  where the
							    search for a name‐
							    space  or  command
							    should   be	  con‐
							    ducted relative to
							    when  the	search
							    term is not rooted
							    at	 the	global
							    namespace.	  NULL
							    indicates the cur‐
							    rent namespace.

       int flags (in)					    OR-ed  combination
							    of	bits  control‐
							    ling    how	   the
							    search  is	to  be
							    performed.	   The
							    following	 flags
							    are	    supported:
							    TCL_GLOBAL_ONLY
							    (indicates	  that
							    the search is  al‐
							    ways  to  be  con‐
							    ducted relative to
							    the	 global	 name‐
							    space),  TCL_NAME‐
							    SPACE_ONLY	 (just
							    for	  Tcl_FindCom‐
							    mand;    indicates
							    that the search is
							    always  to be con‐
							    ducted relative to
							    the	 context name‐
							    space),	   and
							    TCL_LEAVE_ERR_MSG
							    (indicates that an
							    error      message
							    should be left  in
							    the interpreter if
							    the search fails.)

       Tcl_Obj *handlerPtr (in)				    A script  fragment
							    to be installed as
							    the	 unknown  com‐
							    mand  handler  for
							    the namespace,  or
							    NULL  to reset the
							    handler to its de‐
							    fault.
______________________________________________________________________________

DESCRIPTION
       Namespaces are hierarchic naming contexts that can contain commands and
       variables.  They also maintain a list of patterns that  describes  what
       commands	 are exported, and can import commands that have been exported
       by other namespaces.  Namespaces can also be  manipulated  through  the
       Tcl command namespace.

       The Tcl_Namespace structure encapsulates a namespace, and is guaranteed
       to have the following fields in it: name (the local name of  the	 name‐
       space,  with no namespace separator characters in it, with empty denot‐
       ing the global namespace), fullName (the fully specified	 name  of  the
       namespace), clientData, deleteProc (the values specified in the call to
       Tcl_CreateNamespace), and parentPtr (a pointer to the containing	 name‐
       space, or NULL for the global namespace.)

       Tcl_CreateNamespace  creates a new namespace.  The deleteProc will have
       the following type signature:

	      typedef void Tcl_NamespaceDeleteProc(
		      ClientData clientData);

       Tcl_DeleteNamespace deletes a namespace, calling the deleteProc defined
       for the namespace (if any).

       Tcl_AppendExportList  retrieves	the  export  patterns  for a namespace
       given namespace and appends them (as list items) to objPtr.

       Tcl_Export sets and appends to the export  patterns  for	 a  namespace.
       Patterns are appended unless the resetListFirst flag is true.

       Tcl_Import  imports commands matching a pattern into a namespace.  Note
       that the pattern must include the name of the namespace to import from.
       This  function returns TCL_ERROR if an attempt to import a command over
       an existing command is made, unless the allowOverwrite  flag  has  been
       set.

       Tcl_ForgetImport removes imports matching a pattern.

       Tcl_GetCurrentNamespace	returns	 the  current  namespace for an inter‐
       preter.

       Tcl_GetGlobalNamespace returns the global namespace for an interpreter.

       Tcl_FindNamespace searches for a namespace named name within  the  con‐
       text  of the namespace contextNsPtr.  If the namespace cannot be found,
       NULL is returned.

       Tcl_FindCommand searches for a command named name within the context of
       the  namespace  contextNsPtr.   If the command cannot be found, NULL is
       returned.

       Tcl_GetNamespaceUnknownHandler returns the unknown command handler  for
       the namespace, or NULL if none is set.

       Tcl_SetNamespaceUnknownHandler sets the unknown command handler for the
       namespace. If handlerPtr is NULL, then the handler is reset to its  de‐
       fault.

SEE ALSO
       Tcl_CreateCommand(3), Tcl_ListObjAppendList(3), Tcl_SetVar(3)

KEYWORDS
       namespace, command



Tcl				      8.5		      Tcl_Namespace(3)

Tcl_RegExpMatch(3)	    Tcl Library Procedures	    Tcl_RegExpMatch(3)



______________________________________________________________________________

NAME
       Tcl_RegExpMatch,	 Tcl_RegExpCompile,  Tcl_RegExpExec,  Tcl_RegExpRange,
       Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj,  Tcl_RegExpExecObj,  Tcl_Reg‐
       ExpGetInfo - Pattern matching with regular expressions

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_RegExpMatchObj(interp, textObj, patObj)

       int
       Tcl_RegExpMatch(interp, text, pattern)

       Tcl_RegExp
       Tcl_RegExpCompile(interp, pattern)

       int
       Tcl_RegExpExec(interp, regexp, text, start)

       void
       Tcl_RegExpRange(regexp, index, startPtr, endPtr)

       Tcl_RegExp
       Tcl_GetRegExpFromObj(interp, patObj, cflags)

       int
       Tcl_RegExpExecObj(interp, regexp, textObj, offset, nmatches, eflags)

       void
       Tcl_RegExpGetInfo(regexp, infoPtr)

ARGUMENTS
       Tcl_Interp *interp (in)		    Tcl	 interpreter  to use for error
					    reporting.	The interpreter may be
					    NULL  if no error reporting is de‐
					    sired.

       Tcl_Obj *textObj (in/out)	    Refers to the value from which  to
					    get	 the  text to search.  The in‐
					    ternal representation of the value
					    may	 be  converted	to a form that
					    can be efficiently searched.

       Tcl_Obj *patObj (in/out)		    Refers to the value from which  to
					    get a regular expression. The com‐
					    piled regular expression is cached
					    in the value.

       const char *text (in)		    Text  to search for a match with a
					    regular expression.

       const char *pattern (in)		    String in the form	of  a  regular
					    expression pattern.

       Tcl_RegExp regexp (in)		    Compiled regular expression.  Must
					    have been returned	previously  by
					    Tcl_GetRegExpFromObj or Tcl_RegEx‐
					    pCompile.

       const char *start (in)		    If text is just a portion of  some
					    other  string, this argument iden‐
					    tifies the beginning of the larger
					    string.   If it is not the same as
					    text, then no “^” matches will  be
					    allowed.

       int index (in)			    Specifies  which range is desired:
					    0 means the range  of  the	entire
					    match,  1  or  greater  means  the
					    range that matched a parenthesized
					    sub-expression.

       const char **startPtr (out)	    The address of the first character
					    in the range is  stored  here,  or
					    NULL if there is no such range.

       const char **endPtr (out)	    The	 address of the character just
					    after the last one in the range is
					    stored  here,  or NULL if there is
					    no such range.

       int cflags (in)			    OR-ed combination of the  compila‐
					    tion    flags    TCL_REG_ADVANCED,
					    TCL_REG_EXTENDED,	TCL_REG_BASIC,
					    TCL_REG_EXPANDED,	TCL_REG_QUOTE,
					    TCL_REG_NOCASE,   TCL_REG_NEWLINE,
					    TCL_REG_NLSTOP,    TCL_REG_NLANCH,
					    TCL_REG_NOSUB,  and	  TCL_REG_CAN‐
					    MATCH. See below for more informa‐
					    tion.

       int offset (in)			    The character offset into the text
					    where  matching should begin.  The
					    value of the offset has no	impact
					    on	^  matches.   This behavior is
					    controlled by eflags.

       int nmatches (in)		    The number of matching  subexpres‐
					    sions  that	 should	 be remembered
					    for later use.  If this  value  is
					    0, then no subexpression match in‐
					    formation will  be	computed.   If
					    the	 value	is -1, then all of the
					    matching  subexpressions  will  be
					    remembered.	  Any other value will
					    be taken as the maximum number  of
					    subexpressions to remember.

       int eflags (in)			    OR-ed combination of the execution
					    flags      TCL_REG_NOTBOL	   and
					    TCL_REG_NOTEOL. See below for more
					    information.

       Tcl_RegExpInfo *infoPtr (out)	    The address of the location	 where
					    information about a previous match
					    should be stored by Tcl_RegExpGet‐
					    Info.
______________________________________________________________________________

DESCRIPTION
       Tcl_RegExpMatch determines whether its pattern argument matches regexp,
       where regexp is interpreted as a regular expression using the rules  in
       the re_syntax reference page.  If there is a match then Tcl_RegExpMatch
       returns 1.  If there is no match then Tcl_RegExpMatch returns 0.	 If an
       error occurs in the matching process (e.g. pattern is not a valid regu‐
       lar expression) then Tcl_RegExpMatch returns -1	and  leaves  an	 error
       message	in  the	 interpreter result.  Tcl_RegExpMatchObj is similar to
       Tcl_RegExpMatch except it operates on the Tcl values textObj and patObj
       instead of UTF strings.	Tcl_RegExpMatchObj is generally more efficient
       than Tcl_RegExpMatch, so it is the preferred interface.

       Tcl_RegExpCompile, Tcl_RegExpExec, and Tcl_RegExpRange  provide	lower-
       level access to the regular expression pattern matcher.	Tcl_RegExpCom‐
       pile compiles a regular expression string into the internal  form  used
       for  efficient  pattern matching.  The return value is a token for this
       compiled form, which can be used in subsequent calls to	Tcl_RegExpExec
       or Tcl_RegExpRange.  If an error occurs while compiling the regular ex‐
       pression then Tcl_RegExpCompile returns NULL and leaves an  error  mes‐
       sage  in the interpreter result.	 Note:	the return value from Tcl_Reg‐
       ExpCompile is only valid up to the next call to Tcl_RegExpCompile;   it
       is not safe to retain these values for long periods of time.

       Tcl_RegExpExec executes the regular expression pattern matcher.	It re‐
       turns 1 if text contains a range of characters that match regexp, 0  if
       no match is found, and -1 if an error occurs.  In the case of an error,
       Tcl_RegExpExec leaves an error message in the interpreter result.  When
       searching  a  string for multiple matches of a pattern, it is important
       to distinguish between the start of the original string and  the	 start
       of  the current search.	For example, when searching for the second oc‐
       currence of a match, the text argument might  point  to	the  character
       just  after  the first match;  however, it is important for the pattern
       matcher to know that this is not the start of  the  entire  string,  so
       that  it	 does  not allow “^” atoms in the pattern to match.  The start
       argument provides this information by pointing  to  the	start  of  the
       overall	string	containing  text.  Start will be less than or equal to
       text;  if it is less than text then no ^ matches will be allowed.

       Tcl_RegExpRange may be invoked after Tcl_RegExpExec returns;   it  pro‐
       vides detailed information about what ranges of the string matched what
       parts of the pattern.  Tcl_RegExpRange returns a pair  of  pointers  in
       *startPtr and *endPtr that identify a range of characters in the source
       string for the most recent call	to  Tcl_RegExpExec.   Index  indicates
       which  of  several ranges is desired: if index is 0, information is re‐
       turned about the overall range of characters that  matched  the	entire
       pattern;	 otherwise, information is returned about the range of charac‐
       ters that matched the index'th parenthesized subexpression  within  the
       pattern.	  If  there  is	 no  range corresponding to index then NULL is
       stored in *startPtr and *endPtr.

       Tcl_GetRegExpFromObj,  Tcl_RegExpExecObj,  and  Tcl_RegExpGetInfo   are
       value  interfaces  that	provide	 the  most  direct  control  of	 Henry
       Spencer's regular expression library.  For users that  need  to	modify
       compilation  and execution options directly, it is recommended that you
       use these interfaces instead of calling the internal regexp  functions.
       These  interfaces  handle the details of UTF to Unicode translations as
       well as providing improved performance through caching in  the  pattern
       and string values.

       Tcl_GetRegExpFromObj  attempts  to return a compiled regular expression
       from the patObj.	 If the value does not already contain a compiled reg‐
       ular  expression	 it  will attempt to create one from the string in the
       value and assign it to the internal representation of the patObj.   The
       return  value of this function is of type Tcl_RegExp.  The return value
       is a token for this compiled form, which	 can  be  used	in  subsequent
       calls  to  Tcl_RegExpExecObj  or Tcl_RegExpGetInfo.  If an error occurs
       while compiling the regular expression  then  Tcl_GetRegExpFromObj  re‐
       turns  NULL and leaves an error message in the interpreter result.  The
       regular expression token can be used as long as the internal  represen‐
       tation of patObj refers to the compiled form.  The cflags argument is a
       bit-wise OR of zero or more of the following  flags  that  control  the
       compilation of patObj:

	 TCL_REG_ADVANCED
		Compile advanced regular expressions (“ARE”s).	This mode cor‐
		responds to the normal regular expression syntax  accepted  by
		the Tcl regexp and regsub commands.

	 TCL_REG_EXTENDED
		Compile extended regular expressions (“ERE”s).	This mode cor‐
		responds to the regular expression syntax  recognized  by  Tcl
		8.0 and earlier versions.

	 TCL_REG_BASIC
		Compile	 basic regular expressions (“BRE”s).  This mode corre‐
		sponds to the regular expression syntax recognized  by	common
		Unix  utilities	 like sed and grep.  This is the default if no
		flags are specified.

	 TCL_REG_EXPANDED
		Compile the regular expression (basic, extended, or  advanced)
		using  an expanded syntax that allows comments and whitespace.
		This mode causes non-backslashed non-bracket-expression	 white
		space and #-to-end-of-line comments to be ignored.

	 TCL_REG_QUOTE
		Compile a literal string, with all characters treated as ordi‐
		nary characters.

	 TCL_REG_NOCASE
		Compile for matching that ignores  upper/lower	case  distinc‐
		tions.

	 TCL_REG_NEWLINE
		Compile	 for  newline-sensitive matching.  By default, newline
		is a completely ordinary character with no special meaning  in
		either	regular	 expressions or strings.  With this flag, “[^”
		bracket expressions and “.”  never match newline, “^”  matches
		an  empty  string  after any newline in addition to its normal
		function, and “$” matches an empty string before  any  newline
		in  addition  to its normal function.  REG_NEWLINE is the bit-
		wise OR of REG_NLSTOP and REG_NLANCH.

	 TCL_REG_NLSTOP
		Compile for partial newline-sensitive matching, with  the  be‐
		havior	of “[^” bracket expressions and “.”  affected, but not
		the behavior of “^” and “$”.  In this mode, “[^”  bracket  ex‐
		pressions and “.”  never match newline.

	 TCL_REG_NLANCH
		Compile	 for  inverse partial newline-sensitive matching, with
		the behavior of “^” and “$” (the “anchors”) affected, but  not
		the  behavior  of  “[^”	 bracket expressions and “.”.  In this
		mode “^” matches an empty string after any newline in addition
		to its normal function, and “$” matches an empty string before
		any newline in addition to its normal function.

	 TCL_REG_NOSUB
		Compile for matching that reports only success or failure, not
		what  was  matched.  This reduces compile overhead and may im‐
		prove performance.  Subsequent calls to	 Tcl_RegExpGetInfo  or
		Tcl_RegExpRange will not report any match information.

	 TCL_REG_CANMATCH
		Compile	 for matching that reports the potential to complete a
		partial match given more text (see below).

       Only one	 of  TCL_REG_EXTENDED,	TCL_REG_ADVANCED,  TCL_REG_BASIC,  and
       TCL_REG_QUOTE may be specified.

       Tcl_RegExpExecObj  executes the regular expression pattern matcher.  It
       returns 1 if objPtr contains a range of characters that match regexp, 0
       if no match is found, and -1 if an error occurs.	 In the case of an er‐
       ror, Tcl_RegExpExecObj leaves an error message in the  interpreter  re‐
       sult.   The nmatches value indicates to the matcher how many subexpres‐
       sions are of interest.  If nmatches is 0, then no  subexpression	 match
       information  is	recorded,  which may allow the matcher to make various
       optimizations.  If the value is -1, then all of the  subexpressions  in
       the  pattern  are remembered.  If the value is a positive integer, then
       only that number of subexpressions will be remembered.  Matching begins
       at  the	specified  Unicode  character  index  given by offset.	Unlike
       Tcl_RegExpExec, the behavior of anchors is not affected by  the	offset
       value.  Instead the behavior of the anchors is explicitly controlled by
       the eflags argument, which is a bit-wise OR of zero or more of the fol‐
       lowing flags:

	 TCL_REG_NOTBOL
		The starting character will not be treated as the beginning of
		a line or the beginning of the string, so “^” will  not	 match
		there.	Note that this flag has no effect on how “\A” matches.

	 TCL_REG_NOTEOL
		The  last  character  in the string will not be treated as the
		end of a line or the end of the string, so “$” will not	 match
		there.	Note that this flag has no effect on how “\Z” matches.

       Tcl_RegExpGetInfo  retrieves information about the last match performed
       with a given regular expression regexp.	The infoPtr argument  contains
       a pointer to a structure that is defined as follows:

	      typedef struct Tcl_RegExpInfo {
		  int nsubs;
		  Tcl_RegExpIndices *matches;
		  long extendStart;
	      } Tcl_RegExpInfo;

       The  nsubs field contains a count of the number of parenthesized subex‐
       pressions within the regular  expression.   If  the  TCL_REG_NOSUB  was
       used, then this value will be zero.  The matches field points to an ar‐
       ray of nsubs+1 values that indicate the bounds  of  each	 subexpression
       matched.	 The first element in the array refers to the range matched by
       the entire regular expression, and subsequent  elements	refer  to  the
       parenthesized  subexpressions in the order that they appear in the pat‐
       tern.  Each element is a structure that is defined as follows:

	      typedef struct Tcl_RegExpIndices {
		  long start;
		  long end;
	      } Tcl_RegExpIndices;

       The start and end values are Unicode character indices relative to  the
       offset  location	 within	 objPtr where matching began.  The start index
       identifies the first character of the matched subexpression.   The  end
       index  identifies  the first character after the matched subexpression.
       If the subexpression matched the empty string, then start and end  will
       be  equal.  If the subexpression did not participate in the match, then
       start and end will be set to -1.

       The extendStart field in Tcl_RegExpInfo is only set if the TCL_REG_CAN‐
       MATCH  flag  was	 used.	It indicates the first character in the string
       where a match could occur.  If a match was found, this will be the same
       as  the beginning of the current match.	If no match was found, then it
       indicates the earliest point at which a match might occur if additional
       text  is	 appended  to  the string.  If it is no match is possible even
       with further text, this field will be set to -1.

SEE ALSO
       re_syntax(n)

KEYWORDS
       match, pattern, regular expression, string,  subexpression,  Tcl_RegEx‐
       pIndices, Tcl_RegExpInfo



Tcl				      8.1		    Tcl_RegExpMatch(3)

Tcl_Method(3)		    TclOO Library Functions		 Tcl_Method(3)



______________________________________________________________________________

NAME
       Tcl_ClassSetConstructor,	   Tcl_ClassSetDestructor,   Tcl_MethodDeclar‐
       erClass,	 Tcl_MethodDeclarerObject,  Tcl_MethodIsPublic,	 Tcl_MethodIs‐
       Type, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_Object‐
       ContextInvokeNext,     Tcl_ObjectContextIsFiltering,	Tcl_ObjectCon‐
       textMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs - ma‐
       nipulate methods and method-call contexts

SYNOPSIS
       #include <tclOO.h>

       Tcl_Method
       Tcl_NewMethod(interp, class, nameObj, isPublic,
		     methodTypePtr, clientData)

       Tcl_Method
       Tcl_NewInstanceMethod(interp, object, nameObj, isPublic,
			     methodTypePtr, clientData)

       Tcl_ClassSetConstructor(interp, class, method)

       Tcl_ClassSetDestructor(interp, class, method)

       Tcl_Class
       Tcl_MethodDeclarerClass(method)

       Tcl_Object
       Tcl_MethodDeclarerObject(method)

       Tcl_Obj *
       Tcl_MethodName(method)

       int
       Tcl_MethodIsPublic(method)

       int
       Tcl_MethodIsType(method, methodTypePtr, clientDataPtr)

       int
       Tcl_ObjectContextInvokeNext(interp, context, objc, objv, skip)

       int
       Tcl_ObjectContextIsFiltering(context)

       Tcl_Method
       Tcl_ObjectContextMethod(context)

       Tcl_Object
       Tcl_ObjectContextObject(context)

       int
       Tcl_ObjectContextSkippedArgs(context)

ARGUMENTS
       Tcl_Interp *interp (in/out)	   The interpreter holding the	object
					   or  class  to  create  or  update a
					   method in.

       Tcl_Object object (in)		   The object to create the method in.

       Tcl_Class class (in)		   The class to create the method in.

       Tcl_Obj *nameObj (in)		   The name of the method  to  create.
					   Should  not be NULL unless creating
					   constructors or destructors.

       int isPublic (in)		   A flag saying what  the  visibility
					   of  the  method  is.	 The only sup‐
					   ported public values of  this  flag
					   are	0  for	a non-exported method,
					   and 1 for an exported method.

       Tcl_MethodType *methodTypePtr (in)  A description of the	 type  of  the
					   method  to  create,	or the type of
					   method to compare against.

       ClientData clientData (in)	   A piece of data that is  passed  to
					   the	implementation	of  the method
					   without interpretation.

       ClientData *clientDataPtr (out)	   A pointer to a variable in which to
					   write the clientData value supplied
					   when the  method  was  created.  If
					   NULL, the clientData value will not
					   be retrieved.

       Tcl_Method method (in)		   A reference to a method to query.

       Tcl_ObjectContext context (in)	   A reference to a  method-call  con‐
					   text.  Note	that  client code must
					   not retain a reference  to  a  con‐
					   text.

       int objc (in)			   The	number of arguments to pass to
					   the method implementation.

       Tcl_Obj *const *objv (in)	   An array of arguments  to  pass  to
					   the method implementation.

       int skip (in)			   The	number	of arguments passed to
					   the method implementation  that  do
					   not represent "real" arguments.
______________________________________________________________________________

DESCRIPTION
       A  method  is  an operation carried out on an object that is associated
       with the object. Every method must be attached to either an object or a
       class;  methods	attached  to a class are associated with all instances
       (direct and indirect) of that class.

       Given a method,	the  entity  that  declared  it	 can  be  found	 using
       Tcl_MethodDeclarerClass	which returns the class that the method is at‐
       tached to (or NULL if the method is not	attached  to  any  class)  and
       Tcl_MethodDeclarerObject	 which	returns	 the object that the method is
       attached to (or NULL if the method is not attached to an	 object).  The
       name of the method can be retrieved with Tcl_MethodName and whether the
       method is exported is retrieved with Tcl_MethodIsPublic.	 The  type  of
       the method can also be introspected upon to a limited degree; the func‐
       tion Tcl_MethodIsType returns whether a method is of a particular type,
       assigning  the  per-method  clientData  to  the	variable pointed to by
       clientDataPtr if (that is non-NULL) if the type is matched.

   METHOD CREATION
       Methods are created by Tcl_NewMethod and	 Tcl_NewInstanceMethod,	 which
       create  a method attached to a class or an object respectively. In both
       cases, the nameObj argument gives the name of the method to create, the
       isPublic	 argument  states  whether  the method should be exported ini‐
       tially, the methodTypePtr argument describes the implementation of  the
       method (see the METHOD TYPES section below) and the clientData argument
       gives some implementation-specific data that is passed on to the imple‐
       mentation of the method when it is called.

       When  the  nameObj argument to Tcl_NewMethod is NULL, an unnamed method
       is created, which is used for constructors and destructors.   Construc‐
       tors  should  be	 installed into their class using the Tcl_ClassSetCon‐
       structor function, and destructors (which must not  require  any	 argu‐
       ments)  should  be installed into their class using the Tcl_ClassSetDe‐
       structor function. Unnamed methods should not be	 used  for  any	 other
       purpose, and named methods should not be used as either constructors or
       destructors. Also note that a NULL methodTypePtr is used to provide in‐
       ternal signaling, and should not be used in client code.

   METHOD CALL CONTEXTS
       When  a	method is called, a method-call context reference is passed in
       as one of the arguments to the implementation  function.	 This  context
       can  be	inspected  to provide information about the caller, but should
       not be retained beyond the moment when the method call terminates.

       The method that is being called can be retrieved from  the  context  by
       using Tcl_ObjectContextMethod, and the object that caused the method to
       be invoked can be retrieved with Tcl_ObjectContextObject. The number of
       arguments  that are to be skipped (e.g. the object name and method name
       in a normal method call) is read with Tcl_ObjectContextSkippedArgs, and
       the  context  can also report whether it is working as a filter for an‐
       other method through Tcl_ObjectContextIsFiltering.

       During the execution of a method, the method implementation may	choose
       to  invoke the stages of the method call chain that come after the cur‐
       rent method implementation. This (the core of the next command) is done
       using Tcl_ObjectContextInvokeNext. Note that this function does not ma‐
       nipulate the call-frame stack, unlike the next command; if  the	method
       implementation has pushed one or more extra frames on the stack as part
       of its implementation, it is also responsible for  temporarily  popping
       those frames from the stack while the Tcl_ObjectContextInvokeNext func‐
       tion is executing. Note also that  the  method-call  context  is	 never
       deleted during the execution of this function.

METHOD TYPES
       The  types  of  methods	are described by a pointer to a Tcl_MethodType
       structure, which is defined as:

	      typedef struct {
		  int version;
		  const char *name;
		  Tcl_MethodCallProc *callProc;
		  Tcl_MethodDeleteProc *deleteProc;
		  Tcl_CloneProc *cloneProc;
	      } Tcl_MethodType;

       The version field allows for future expansion  of  the  structure,  and
       should  always  be declared equal to TCL_OO_METHOD_VERSION_CURRENT. The
       name field provides a human-readable name for  the  type,  and  is  the
       value  that  is	exposed	 via the info class methodtype and info object
       methodtype Tcl commands.

       The callProc field gives a function that is called when the  method  is
       invoked; it must never be NULL.

       The deleteProc field gives a function that is used to delete a particu‐
       lar method, and is called when the method is replaced  or  removed;  if
       the  field is NULL, it is assumed that the method's clientData needs no
       special action to delete.

       The cloneProc field is either  a	 function  that	 is  used  to  copy  a
       method's	 clientData (as part of Tcl_CopyObjectInstance) or NULL to in‐
       dicate that the clientData can just be copied directly.

   TCL_METHODCALLPROC FUNCTION SIGNATURE
       Functions matching this signature are called when  the  method  is  in‐
       voked.

	      typedef int Tcl_MethodCallProc(
		      ClientData clientData,
		      Tcl_Interp *interp,
		      Tcl_ObjectContext objectContext,
		      int objc,
		      Tcl_Obj *const *objv);

       The  clientData	argument to a Tcl_MethodCallProc is the value that was
       given when the method was created, the interp is a place	 in  which  to
       execute	scripts and access variables as well as being where to put the
       result of the method, and the objc and objv fields give	the  parameter
       objects to the method. The calling context of the method can be discov‐
       ered through the objectContext argument, and the return	value  from  a
       Tcl_MethodCallProc is any Tcl return code (e.g. TCL_OK, TCL_ERROR).

   TCL_METHODDELETEPROC FUNCTION SIGNATURE
       Functions  matching  this  signature are used when a method is deleted,
       whether through a new method being created or  because  the  object  or
       class is deleted.

	      typedef void Tcl_MethodDeleteProc(
		      ClientData clientData);

       The  clientData	argument to a Tcl_MethodDeleteProc will be the same as
       the value  passed  to  the  clientData  argument	 to  Tcl_NewMethod  or
       Tcl_NewInstanceMethod when the method was created.

   TCL_CLONEPROC FUNCTION SIGNATURE
       Functions  matching  this  signature are used to copy a method when the
       object or class is copied using Tcl_CopyObjectInstance (or oo::copy).

	      typedef int Tcl_CloneProc(
		      Tcl_Interp *interp,
		      ClientData oldClientData,
		      ClientData *newClientDataPtr);

       The interp argument gives a place to write an error  message  when  the
       attempt	to clone the object is to fail, in which case the clone proce‐
       dure must also return TCL_ERROR; it  should  return  TCL_OK  otherwise.
       The  oldClientData  field  to  a Tcl_CloneProc gives the value from the
       method being copied from, and the newClientDataPtr field will point  to
       a variable in which to write the value for the method being copied to.

SEE ALSO
       Class(3), oo::class(n), oo::define(n), oo::object(n)

KEYWORDS
       constructor, method, object




TclOO				      0.1			 Tcl_Method(3)

Filesystem(3)		    Tcl Library Procedures		 Filesystem(3)



______________________________________________________________________________

NAME
       Tcl_FSRegister,	 Tcl_FSUnregister,   Tcl_FSData,  Tcl_FSMountsChanged,
       Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile,  Tcl_FS‐
       CopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDi‐
       rectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile,  Tcl_FSE‐
       valFileEx,  Tcl_FSLoadFile,  Tcl_FSUnloadFile,  Tcl_FSMatchInDirectory,
       Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAt‐
       trsSet,	Tcl_FSFileAttrStrings,	Tcl_FSStat,  Tcl_FSAccess, Tcl_FSOpen‐
       FileChannel,    Tcl_FSGetCwd,	 Tcl_FSChdir,	  Tcl_FSPathSeparator,
       Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalized‐
       Path, Tcl_FSJoinToPath, Tcl_FSConvertToPathType,	 Tcl_FSGetInternalRep,
       Tcl_FSGetTranslatedPath,	  Tcl_FSGetTranslatedStringPath,  Tcl_FSNewNa‐
       tivePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_GetAccessTime‐
       FromStat,	Tcl_GetBlockSizeFromStat,	Tcl_GetBlocksFromStat,
       Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat,  Tcl_GetFSDevice‐
       FromStat,	Tcl_GetFSInodeFromStat,	       Tcl_GetGroupIdFromStat,
       Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTime‐
       FromStat,  Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, Tcl_AllocStatBuf
       - procedures to interact with any filesystem

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_FSRegister(clientData, fsPtr)

       int
       Tcl_FSUnregister(fsPtr)

       void *
       Tcl_FSData(fsPtr)

       Tcl_FSMountsChanged(fsPtr)

       const Tcl_Filesystem *
       Tcl_FSGetFileSystemForPath(pathPtr)

       Tcl_PathType
       Tcl_FSGetPathType(pathPtr)

       int
       Tcl_FSCopyFile(srcPathPtr, destPathPtr)

       int
       Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)

       int
       Tcl_FSCreateDirectory(pathPtr)

       int
       Tcl_FSDeleteFile(pathPtr)

       int
       Tcl_FSRemoveDirectory(pathPtr, recursive, errorPtr)

       int
       Tcl_FSRenameFile(srcPathPtr, destPathPtr)

       Tcl_Obj *
       Tcl_FSListVolumes(void)

       int
       Tcl_FSEvalFileEx(interp, pathPtr, encodingName)

       int
       Tcl_FSEvalFile(interp, pathPtr)

       int
       Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
		      loadHandlePtr, unloadProcPtr)

       int								       │
       Tcl_FSUnloadFile(interp, loadHandle)				       │

       int
       Tcl_FSMatchInDirectory(interp, resultPtr, pathPtr, pattern, types)

       Tcl_Obj *
       Tcl_FSLink(linkNamePtr, toPtr, linkAction)

       int
       Tcl_FSLstat(pathPtr, statPtr)

       int
       Tcl_FSUtime(pathPtr, tval)

       int
       Tcl_FSFileAttrsGet(interp, index, pathPtr, objPtrRef)

       int
       Tcl_FSFileAttrsSet(interp, index, pathPtr, objPtr)

       const char *const *
       Tcl_FSFileAttrStrings(pathPtr, objPtrRef)

       int
       Tcl_FSStat(pathPtr, statPtr)

       int
       Tcl_FSAccess(pathPtr, mode)

       Tcl_Channel
       Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)

       Tcl_Obj *
       Tcl_FSGetCwd(interp)

       int
       Tcl_FSChdir(pathPtr)

       Tcl_Obj *
       Tcl_FSPathSeparator(pathPtr)

       Tcl_Obj *
       Tcl_FSJoinPath(listObj, elements)

       Tcl_Obj *
       Tcl_FSSplitPath(pathPtr, lenPtr)

       int
       Tcl_FSEqualPaths(firstPtr, secondPtr)

       Tcl_Obj *
       Tcl_FSGetNormalizedPath(interp, pathPtr)

       Tcl_Obj *
       Tcl_FSJoinToPath(basePtr, objc, objv)

       int
       Tcl_FSConvertToPathType(interp, pathPtr)

       void *
       Tcl_FSGetInternalRep(pathPtr, fsPtr)

       Tcl_Obj *
       Tcl_FSGetTranslatedPath(interp, pathPtr)

       const char *
       Tcl_FSGetTranslatedStringPath(interp, pathPtr)

       Tcl_Obj *
       Tcl_FSNewNativePath(fsPtr, clientData)

       const void *
       Tcl_FSGetNativePath(pathPtr)

       Tcl_Obj *
       Tcl_FSFileSystemInfo(pathPtr)

       Tcl_StatBuf *
       Tcl_AllocStatBuf()

       Tcl_WideInt							       │
       Tcl_GetAccessTimeFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetBlockSizeFromStat(statPtr)				       │

       Tcl_WideUInt							       │
       Tcl_GetBlocksFromStat(statPtr)					       │

       Tcl_WideInt							       │
       Tcl_GetChangeTimeFromStat(statPtr)				       │

       int								       │
       Tcl_GetDeviceTypeFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetFSDeviceFromStat(statPtr)					       │

       unsigned								       │
       Tcl_GetFSInodeFromStat(statPtr)					       │

       int								       │
       Tcl_GetGroupIdFromStat(statPtr)					       │

       int								       │
       Tcl_GetLinkCountFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetModeFromStat(statPtr)					       │

       Tcl_WideInt							       │
       Tcl_GetModificationTimeFromStat(statPtr)				       │

       Tcl_WideUInt							       │
       Tcl_GetSizeFromStat(statPtr)					       │

       int								       │
       Tcl_GetUserIdFromStat(statPtr)					       │

ARGUMENTS
       const Tcl_Filesystem *fsPtr (in)		   Points to a structure  con‐
						   taining  the	 addresses  of
						   procedures  that   can   be
						   called to perform the vari‐
						   ous filesystem operations.

       Tcl_Obj *pathPtr (in)			   The	path  represented   by
						   this	 value is used for the
						   operation in	 question.  If
						   the	value does not already
						   have an internal path  rep‐
						   resentation,	  it  will  be
						   converted to have one.

       Tcl_Obj *srcPathPtr (in)			   As for  pathPtr,  but  used
						   for	the  source file for a
						   copy or rename operation.

       Tcl_Obj *destPathPtr (in)		   As for  pathPtr,  but  used
						   for	the  destination file‐
						   name for a copy  or	rename
						   operation.

       int recursive (in)			   Whether to remove subdirec‐
						   tories and  their  contents
						   as well.

       const char *encodingName (in)		   The	encoding  of  the data
						   stored in the file  identi‐
						   fied	 by  pathPtr and to be
						   evaluated.

       const char *pattern (in)			   Only files  or  directories
						   matching  this pattern will
						   be returned.

       Tcl_GlobTypeData *types (in)		   Only files  or  directories
						   matching  the type descrip‐
						   tions  contained  in	  this
						   structure will be returned.
						   This parameter may be NULL.

       Tcl_Interp *interp (in)			   Interpreter to  use	either
						   for results, evaluation, or
						   reporting error messages.

       void *clientData (in)			   The native  description  of
						   the path value to create.

       Tcl_Obj *firstPtr (in)			   The	first of two path val‐
						   ues to compare.  The	 value
						   may	be  converted  to path
						   type.

       Tcl_Obj *secondPtr (in)			   The second of two path val‐
						   ues	to  compare. The value
						   may be  converted  to  path
						   type.

       Tcl_Obj *listObj (in)			   The	list  of path elements
						   to operate on with  a  join
						   operation.

       int elements (in)			   The	number	of elements in
						   the listObj which should be
						   joined  together.  If nega‐
						   tive, then all elements are
						   joined.

       Tcl_Obj **errorPtr (out)			   In  the  case  of an error,
						   filled with	a  value  con‐
						   taining  the	 name  of  the
						   file which caused an	 error
						   in  the various copy/rename
						   operations.

       int index (in)				   The index of the  attribute
						   in question.

       Tcl_Obj *objPtr (in)			   The value to set in the op‐
						   eration.

       Tcl_Obj **objPtrRef (out)		   Filled with	a  value  con‐
						   taining  the	 result of the
						   operation.

       Tcl_Obj *resultPtr (out)			   Preallocated value in which
						   to store (using Tcl_ListOb‐
						   jAppendElement) the list of
						   files  or directories which
						   are successfully matched.

       int mode (in)				   Mask consisting of  one  or
						   more	 of  R_OK,  W_OK, X_OK
						   and F_OK.  R_OK,  W_OK  and
						   X_OK	   request    checking
						   whether the file exists and
						   has	 read, write and  exe‐
						   cute	 permissions,  respec‐
						   tively.  F_OK just requests
						   checking for the  existence
						   of the file.

       Tcl_StatBuf *statPtr (out)		   The structure that contains
						   the result  of  a  stat  or
						   lstat operation.

       const char *sym1 (in)			   Name of a procedure to look
						   up in the file's symbol ta‐
						   ble

       const char *sym2 (in)			   Name of a procedure to look
						   up in the file's symbol ta‐
						   ble

       Tcl_PackageInitProc **proc1Ptr (out)	   Filled  with the init func‐
						   tion for this code.

       Tcl_PackageInitProc **proc2Ptr (out)	   Filled with	the  safe-init
						   function for this code.

       void **clientDataPtr (out)		   Filled  with the clientData
						   value  to  pass   to	  this
						   code's unload function when
						   it is called.

       Tcl_LoadHandle *loadHandlePtr (out)	   Filled with an abstract to‐
						   ken representing the loaded
						   file.

       Tcl_FSUnloadFileProc **unloadProcPtr (out)  Filled with the function to
						   use to unload this piece of
						   code.

       Tcl_LoadHandle loadHandle (in)		   Handle to  the  loaded  li‐
						   brary to be unloaded.

       utimbuf *tval (in)			   The access and modification
						   times in this structure are
						   read	 and used to set those
						   values for a given file.

       const char *modeString (in)		   Specifies how the  file  is
						   to  be  accessed.  May have
						   any of the  values  allowed
						   for	the  mode  argument to
						   the Tcl open command.

       int permissions (in)			   POSIX-style	    permission
						   flags  such	as  0644. If a
						   new file is created,	 these
						   permissions	will be set on
						   the created file.

       int *lenPtr (out)			   If  non-NULL,  filled  with
						   the	number	of elements in
						   the split path.

       Tcl_Obj *basePtr (in)			   The base path on  to	 which
						   to join the given elements.
						   May be NULL.

       int objc (in)				   The number of  elements  in
						   objv.

       Tcl_Obj *const objv[] (in)		   The elements to join to the
						   given base path.

       Tcl_Obj *linkNamePtr (in)		   The name of the link to  be
						   created or read.

       Tcl_Obj *toPtr (in)			   What	   the	 link	called
						   linkNamePtr	  should    be
						   linked  to,	or NULL if the
						   symbolic link specified  by
						   linkNamePtr is to be read.

       int linkAction (in)			   OR-ed  combination of flags
						   indicating  what  kind   of
						   link	  should   be  created
						   (will be ignored  if	 toPtr
						   is NULL). Valid bits to set
						   are	       TCL_CREATE_SYM‐
						   BOLIC_LINK	and   TCL_CRE‐
						   ATE_HARD_LINK.   When  both
						   flags  are  set and the un‐
						   derlying filesystem can  do
						   either,  symbolic links are
						   preferred.
______________________________________________________________________________

DESCRIPTION
       There  are  several  reasons  for  calling  the	Tcl_FS	API  functions
       (e.g. Tcl_FSAccess  and	Tcl_FSStat)  rather  than calling system level
       functions like access and stat directly. First, they will  work	cross-
       platform,  so  an  extension which calls them should work unmodified on
       Unix and Windows. Second, the Windows implementation of some  of	 these
       functions fixes some bugs in the system level calls. Third, these func‐
       tion calls deal with any	 “Utf  to  platform-native”  path  conversions
       which  may  be  required (and may cache the results of such conversions
       for greater efficiency on subsequent calls). Fourth, and	 perhaps  most
       importantly,  all  of  these  functions are “virtual filesystem aware”.
       Any virtual filesystem  (VFS  for  short)  which	 has  been  registered
       (through	 Tcl_FSRegister)  may reroute file access to alternative media
       or access methods. This means that all of these functions  (and	there‐
       fore  the  corresponding	 file, glob, pwd, cd, open, etc. Tcl commands)
       may be operate on “files” which are not	native	files  in  the	native
       filesystem.  This  also means that any Tcl extension which accesses the
       filesystem (FS for short) through this API  is  automatically  “virtual
       filesystem  aware”.   Of	 course,  if  an extension accesses the native
       filesystem directly (through platform-specific APIs, for example), then
       Tcl cannot intercept such calls.

       If appropriate VFSes have been registered, the “files” may, to give two
       examples, be remote (e.g. situated on a remote ftp server) or  archived
       (e.g. lying inside a .zip archive). Such registered filesystems provide
       a lookup table of functions to implement all or some of the functional‐
       ity listed here. Finally, the Tcl_FSStat and Tcl_FSLstat calls abstract
       away from what the “struct stat” buffer is actually declared to be, al‐
       lowing  the same code to be used both on systems with and systems with‐
       out support for files larger than 2GB in size.

       The Tcl_FS API is Tcl_Obj-ified and may cache internal  representations
       and  other  path-related	 strings (e.g. the current working directory).
       One side-effect of this is that one must not pass in values with a ref‐
       erence count of zero to any of these functions. If such calls were han‐
       dled, they might result in memory leaks (under some circumstances,  the
       filesystem  code may wish to retain a reference to the passed in value,
       and so one must not assume that after any of these  calls  return,  the
       value  still  has  a  reference count of zero - it may have been incre‐
       mented) or in a direct segmentation fault (or other memory  access  er‐
       ror)  due  to  the value being freed part way through the complex value
       manipulation required to ensure that the path is fully  normalized  and
       absolute	 for  filesystem  determination. The practical lesson to learn
       from this is that

	      Tcl_Obj *path = Tcl_NewStringObj(...);
	      Tcl_FSWhatever(path);
	      Tcl_DecrRefCount(path);

       is wrong, and may cause memory errors. The path must have its reference
       count  incremented  before  passing it in, or decrementing it. For this
       reason, values with a reference count of zero are considered not to  be
       valid  filesystem paths and calling any Tcl_FS API function with such a
       value will result in no action being taken.

   FS API FUNCTIONS
       Tcl_FSCopyFile attempts to copy the file given  by  srcPathPtr  to  the
       path  name given by destPathPtr. If the two paths given lie in the same
       filesystem (according to Tcl_FSGetFileSystemForPath) then that filesys‐
       tem's  “copy  file”  function is called (if it is non-NULL).  Otherwise
       the function returns -1 and sets the errno global  C  variable  to  the
       “EXDEV” POSIX error code (which signifies a “cross-domain link”).

       Tcl_FSCopyDirectory  attempts to copy the directory given by srcPathPtr
       to the path name given by destPathPtr. If the two paths	given  lie  in
       the same filesystem (according to Tcl_FSGetFileSystemForPath) then that
       filesystem's “copy file” function is called (if it is non-NULL).	  Oth‐
       erwise  the function returns -1 and sets the errno global C variable to
       the “EXDEV” POSIX error code (which signifies a “cross-domain link”).

       Tcl_FSCreateDirectory attempts to create the directory given by pathPtr
       by calling the owning filesystem's “create directory” function.

       Tcl_FSDeleteFile	 attempts to delete the file given by pathPtr by call‐
       ing the owning filesystem's “delete file” function.

       Tcl_FSRemoveDirectory attempts to remove the directory given by pathPtr
       by calling the owning filesystem's “remove directory” function.

       Tcl_FSRenameFile attempts to rename the file or directory given by src‐
       PathPtr to the path name given by destPathPtr. If the two  paths	 given
       lie  in	the  same filesystem (according to Tcl_FSGetFileSystemForPath)
       then that filesystem's “rename file” function is called (if it is  non-
       NULL).  Otherwise  the  function returns -1 and sets the errno global C
       variable to the “EXDEV” POSIX error code (which signifies a  “cross-do‐
       main link”).

       Tcl_FSListVolumes calls each filesystem which has a non-NULL “list vol‐
       umes” function and asks them to return their list of root  volumes.  It
       accumulates the return values in a list which is returned to the caller
       (with a reference count of 0).

       Tcl_FSEvalFileEx reads the file given by	 pathPtr  using	 the  encoding
       identified  by encodingName and evaluates its contents as a Tcl script.
       It returns the same information as Tcl_EvalObjEx.  If  encodingName  is
       NULL,  the  system  encoding is used for reading the file contents.  If
       the file could not be read then a Tcl error is returned to describe why
       the  file  could not be read.  The eofchar for files is “\x1A” (^Z) for
       all platforms.  If you require a “^Z” in code  for  string  comparison,
       you  can use “\x1A”, which will be safely substituted by the Tcl inter‐
       preter into “^Z”.  Tcl_FSEvalFile is a simpler version  of  Tcl_FSEval‐
       FileEx that always uses the system encoding when reading the file.

       Tcl_FSLoadFile dynamically loads a binary code file into memory and re‐
       turns the addresses of two procedures within that file, if they are de‐
       fined. The appropriate function for the filesystem to which pathPtr be‐
       longs will be called. If that filesystem does not implement this	 func‐
       tion  (most  virtual filesystems will not, because of OS limitations in
       dynamically loading binary code), Tcl will attempt to copy the file  to
       a  temporary  directory and load that temporary file.  Tcl_FSUnloadFile │
       reverses the operation, asking for the library indicated by  the	 load‐ │
       Handle  to  be removed from the process. Note that, unlike with the un‐ │
       load command, this does not give the library any opportunity  to	 clean │
       up.

       Both  the  above functions return a standard Tcl completion code. If an
       error occurs, an error message is left in the interp's result.

       The token provided via the variable indicated by loadHandlePtr  may  be │
       used with Tcl_FindSymbol.

       Tcl_FSMatchInDirectory  is used by the globbing code to search a direc‐
       tory for all files which match a given pattern. The  appropriate	 func‐
       tion for the filesystem to which pathPtr belongs will be called.

       The  return  value is a standard Tcl result indicating whether an error
       occurred in globbing. Error messages are placed in interp  (unless  in‐
       terp is NULL, which is allowed), but good results are placed in the re‐
       sultPtr given.

       Note that the glob code implements recursive  patterns  internally,  so
       this  function  will  only ever be passed simple patterns, which can be
       matched using the logic of string match. To handle recursion, Tcl  will
       call  this  function  frequently	 asking only for directories to be re‐
       turned. A special case of being called with a  NULL  pattern  indicates
       that the path needs to be checked only for the correct type.

       Tcl_FSLink  replaces the library version of readlink, and extends it to
       support the  creation  of  links.  The  appropriate  function  for  the
       filesystem to which linkNamePtr belongs will be called.

       If  the toPtr is NULL, a “read link” action is performed. The result is
       a Tcl_Obj specifying  the  contents  of	the  symbolic  link  given  by
       linkNamePtr, or NULL if the link could not be read. The result is owned
       by the caller, which should call Tcl_DecrRefCount when the result is no
       longer  needed.	If  the toPtr is not NULL, Tcl should create a link of
       one of the types passed in in the linkAction flag.   This  flag	is  an
       OR'ed combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CREATE_HARD_LINK.
       Where a choice exists (i.e. more than one flag is passed in),  the  Tcl
       convention  is  to  prefer  symbolic links. When a link is successfully
       created, the return value should be toPtr (which is  therefore  already
       owned by the caller). If unsuccessful, NULL is returned.

       Tcl_FSLstat  fills  the	Tcl_StatBuf structure statPtr with information
       about the specified file. You do not need any access rights to the file
       to  get	this information but you need search rights to all directories
       named in the path leading to the file. The  Tcl_StatBuf	structure  in‐
       cludes  info  regarding	device, inode (always 0 on Windows), privilege
       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
       id  (always 0 on Windows), rdev (same as device on Windows), size, last
       access time, last modification time, and	 last  metadata	 change	 time.
       See PORTABLE STAT RESULT API for a description of how to write portable
       code to allocate and access the Tcl_StatBuf structure.

       If path exists, Tcl_FSLstat returns 0 and the stat structure is	filled
       with data. Otherwise, -1 is returned, and no stat info is given.

       Tcl_FSUtime replaces the library version of utime.

       This  returns 0 on success and -1 on error (as per the utime documenta‐
       tion). If successful, the function will update the “atime” and  “mtime”
       values of the file given.

       Tcl_FSFileAttrsGet  implements  read  access  for the hookable file at‐
       tributes subcommand. The appropriate function  for  the	filesystem  to
       which pathPtr belongs will be called.

       If  the	result	is TCL_OK, then a value was placed in objPtrRef, which
       will only be temporarily valid (unless Tcl_IncrRefCount is called).

       Tcl_FSFileAttrsSet implements write access for the  hookable  file  at‐
       tributes	 subcommand.  The  appropriate	function for the filesystem to
       which pathPtr belongs will be called.

       Tcl_FSFileAttrStrings implements part of the hookable  file  attributes
       subcommand.  The appropriate function for the filesystem to which path‐
       Ptr belongs will be called.

       The called procedure may either return an array of strings, or may  in‐
       stead  return  NULL  and place a Tcl list into the given objPtrRef. Tcl
       will take that list and first increment its reference count before  us‐
       ing  it.	  On  completion of that use, Tcl will decrement its reference
       count. Hence if the list should be disposed of by  Tcl  when  done,  it
       should  have  a	reference count of zero, and if the list should not be
       disposed of, the filesystem should ensure it retains a reference	 count
       to the value.

       Tcl_FSAccess checks whether the process would be allowed to read, write
       or test for existence of the file (or other  filesystem	object)	 whose
       name  is pathname. If pathname is a symbolic link on Unix, then permis‐
       sions of the file referred by this symbolic link are tested.

       On success (all requested permissions granted), zero  is	 returned.  On
       error  (at least one bit in mode asked for a permission that is denied,
       or some other error occurred), -1 is returned.

       Tcl_FSStat fills the Tcl_StatBuf	 structure  statPtr  with  information
       about the specified file. You do not need any access rights to the file
       to get this information but you need search rights to  all  directories
       named  in  the  path leading to the file. The Tcl_StatBuf structure in‐
       cludes info regarding device, inode (always 0  on  Windows),  privilege
       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
       id (always 0 on Windows), rdev (same as device on Windows), size,  last
       access  time,  last  modification  time, and last metadata change time.
       See PORTABLE STAT RESULT API for a description of how to write portable
       code to allocate and access the Tcl_StatBuf structure.

       If  path	 exists, Tcl_FSStat returns 0 and the stat structure is filled
       with data. Otherwise, -1 is returned, and no stat info is given.

       Tcl_FSOpenFileChannel opens a file specified by pathPtr and  returns  a
       channel	handle	that  can  be  used to perform input and output on the
       file. This API is modeled after the fopen procedure of the  Unix	 stan‐
       dard  I/O  library.  The syntax and meaning of all arguments is similar
       to those given in the Tcl open command when opening a file.  If an  er‐
       ror  occurs  while  opening  the channel, Tcl_FSOpenFileChannel returns
       NULL and records	 a  POSIX  error  code	that  can  be  retrieved  with
       Tcl_GetErrno.   In addition, if interp is non-NULL, Tcl_FSOpenFileChan‐
       nel leaves an error message in interp's result after any error.

       The newly created channel is not	 registered  in	 the  supplied	inter‐
       preter;	to  register it, use Tcl_RegisterChannel.  If one of the stan‐
       dard channels, stdin, stdout or stderr was previously closed,  the  act
       of  creating  the  new channel also assigns it as a replacement for the
       standard channel.

       Tcl_FSGetCwd replaces the library version of getcwd.

       It returns the Tcl library's current working  directory.	 This  may  be
       different  to  the  native  platform's working directory, which happens
       when the current working directory is not in the native filesystem.

       The result is a pointer to a Tcl_Obj specifying the current  directory,
       or  NULL	 if  the current directory could not be determined. If NULL is
       returned, an error message is left in the interp's result.

       The result already has its reference count incremented for the  caller.
       When  it	 is  no	 longer	 needed, that reference count should be decre‐
       mented. This is needed for thread-safety purposes,  to  allow  multiple
       threads	to  access  this and related functions, while ensuring the re‐
       sults are always valid.

       Tcl_FSChdir replaces the library version of chdir. The path is  normal‐
       ized  and  then	passed	to  the	 filesystem  which  claims it. If that
       filesystem does not implement this function, Tcl	 will  fallback	 to  a
       combination  of	stat  and access to check whether the directory exists
       and has appropriate permissions.

       For results, see chdir documentation. If successful, we keep  a	record
       of  the	successful  path in cwdPathPtr for subsequent calls to Tcl_FS‐
       GetCwd.

       Tcl_FSPathSeparator returns the separator character to be used for most
       specific	 element  of the path specified by pathPtr (i.e. the last part
       of the path).

       The separator is returned as a Tcl_Obj containing a string of length 1.
       If the path is invalid, NULL is returned.

       Tcl_FSJoinPath  takes  the  given  Tcl_Obj,  which must be a valid list
       (which is allowed to have a reference count of zero), and  returns  the
       path  value  given  by considering the first elements elements as valid
       path segments (each path segment may be a complete path, a partial path
       or  just a single possible directory or file name). If any path segment
       is actually an absolute path, then all prior  path  segments  are  dis‐
       carded.	If elements is less than 0, we use the entire list.

       It  is  possible	 that the returned value is actually an element of the
       given list, so the caller should be careful to increment the  reference
       count of the result before freeing the list.

       The  returned  value,  typically with a reference count of zero (but it
       could be shared under some conditions), contains the joined  path.  The
       caller must add a reference count to the value before using it. In par‐
       ticular, the returned value could be an element of the given  list,  so
       freeing the list might free the value prematurely if no reference count
       has been taken.	If the number of elements is zero, then	 the  returned
       value will be an empty-string Tcl_Obj.

       Tcl_FSSplitPath	takes the given Tcl_Obj, which should be a valid path,
       and returns a Tcl list value containing each segment of that path as an
       element.	  It  returns  a list value with a reference count of zero. If
       the passed in lenPtr is non-NULL, the variable it points to will be up‐
       dated to contain the number of elements in the returned list.

       Tcl_FSEqualPaths	 tests	whether the two paths given represent the same
       filesystem object.  It returns 1 if the paths are equal, and 0 if  they
       are different. If either path is NULL, 0 is always returned.

       Tcl_FSGetNormalizedPath	attempts  to  extract from the given Tcl_Obj a
       unique normalized path representation, whose string value can  be  used
       as a unique identifier for the file.

       It returns the normalized path value, owned by Tcl, or NULL if the path
       was invalid or could otherwise not be successfully converted.   Extrac‐
       tion  of	 absolute,  normalized	paths  is  very efficient (because the
       filesystem operates on these representations internally), although  the
       result  when the filesystem contains numerous symbolic links may not be
       the most user-friendly version of a path. The return value is owned  by
       Tcl and has a lifetime equivalent to that of the pathPtr passed in (un‐
       less that is a relative path, in which case the normalized  path	 value
       may  be	freed any time the cwd changes) - the caller can of course in‐
       crement the reference count if it wishes to maintain a copy for longer.

       Tcl_FSJoinToPath takes the given value, which should usually be a valid
       path or NULL, and joins onto it the array of paths segments given.

       Returns	a  value, typically with reference count of zero (but it could
       be shared under some  conditions),  containing  the  joined  path.  The
       caller  must add a reference count to the value before using it. If any
       of the values passed into this function (pathPtr or path elements) have
       a  reference  count  of zero, they will be freed when this function re‐
       turns.

       Tcl_FSConvertToPathType tries to convert the given Tcl_Obj to  a	 valid
       Tcl path type, taking account of the fact that the cwd may have changed
       even if this value is already supposedly	 of  the  correct  type.   The
       filename may begin with “~” (to indicate current user's home directory)
       or “~<user>” (to indicate any user's home directory).

       If the conversion succeeds (i.e. the value is a valid path  in  one  of
       the  current filesystems), then TCL_OK is returned. Otherwise TCL_ERROR
       is returned, and an error message may be left in the interpreter.

       Tcl_FSGetInternalRep extracts the internal representation  of  a	 given
       path  value,  in	 the  given filesystem. If the path value belongs to a
       different filesystem, we return NULL. If the internal representation is
       currently  NULL, we attempt to generate it, by calling the filesystem's
       Tcl_FSCreateInternalRepProc.

       Returns NULL or a valid internal	 path  representation.	This  internal
       representation  is cached, so that repeated calls to this function will
       not require additional conversions.

       Tcl_FSGetTranslatedPath attempts to extract the	translated  path  from
       the given Tcl_Obj.

       If  the	translation succeeds (i.e. the value is a valid path), then it
       is returned. Otherwise NULL will be returned, and an error message  may
       be  left	 in the interpreter. A “translated” path is one which contains
       no “~” or “~user” sequences (these have been expanded to their  current
       representation  in  the filesystem). The value returned is owned by the
       caller, which must store it or call Tcl_DecrRefCount to	ensure	memory
       is  freed.  This function is of little practical use, and Tcl_FSGetNor‐
       malizedPath or Tcl_FSGetNativePath are usually better functions to  use
       for most purposes.

       Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
       but returns a character string or NULL.	The string returned is dynami‐
       cally  allocated	 and  owned by the caller, which must store it or call
       ckfree to ensure it is freed. Again, Tcl_FSGetNormalizedPath or Tcl_FS‐
       GetNativePath are usually better functions to use for most purposes.

       Tcl_FSNewNativePath  performs  something	 like the reverse of the usual
       obj->path->nativerep conversions. If some code retrieves a path in  na‐
       tive form (from, e.g. readlink or a native dialog), and that path is to
       be used at the Tcl level, then calling this function  is	 an  efficient
       way of creating the appropriate path value type.

       The  resulting  value is a pure “path” value, which will only receive a
       UTF-8 string representation if that is required by some Tcl code.

       Tcl_FSGetNativePath is for use by the Win/Unix native  filesystems,  so
       that  they can easily retrieve the native (char* or TCHAR*) representa‐
       tion of a path. This function is a convenience wrapper  around  Tcl_FS‐
       GetInternalRep.	It  may be desirable in the future to have non-string-
       based native representations (for example, on macOS,  a	representation
       using  a fileSpec of FSRef structure would probably be more efficient).
       On Windows a full Unicode representation would allow for paths  of  un‐
       limited	length.	 Currently  the	 representation	 is simply a character
       string which may contain either the relative path or a complete,	 abso‐
       lute normalized path in the native encoding (complex conditions dictate
       which of these will be provided, so neither can be relied upon,	unless
       the path is known to be absolute). If you need a native path which must
       be absolute, then you should ask for the native version of a normalized
       path.  If for some reason a non-absolute, non-normalized version of the
       path is needed, that must be constructed separately (e.g. using Tcl_FS‐
       GetTranslatedPath).

       The  native  representation  is	cached	so that repeated calls to this
       function will not require additional conversions. The return  value  is
       owned  by  Tcl  and  has	 a  lifetime equivalent to that of the pathPtr
       passed in (unless that is a relative path, in  which  case  the	native
       representation may be freed any time the cwd changes).

       Tcl_FSFileSystemInfo  returns a list of two elements. The first element
       is the name  of	the  filesystem	 (e.g.	 “native”,  “vfs”,  “zip”,  or
       “prowrap”, perhaps), and the second is the particular type of the given
       path within that filesystem (which is filesystem dependent). The second
       element may be empty if the filesystem does not provide a further cate‐
       gorization of files.

       A valid list value is returned, unless the path	value  is  not	recog‐
       nized, when NULL will be returned.

       Tcl_FSGetFileSystemForPath  returns  a  pointer	to  the Tcl_Filesystem
       which accepts this path as valid.

       If no filesystem will accept the path, NULL is returned.

       Tcl_FSGetPathType determines whether the given path is relative to  the
       current directory, relative to the current volume, or absolute.

       It    returns   one   of	  TCL_PATH_ABSOLUTE,   TCL_PATH_RELATIVE,   or
       TCL_PATH_VOLUME_RELATIVE

   PORTABLE STAT RESULT API
       Tcl_AllocStatBuf allocates a Tcl_StatBuf on the system heap (which  may
       be  deallocated	by  being passed to ckfree). This allows extensions to
       invoke Tcl_FSStat and Tcl_FSLstat without being dependent on  the  size
       of the buffer. That in turn depends on the flags used to build Tcl.

       The  portable  fields  of a Tcl_StatBuf may be read using the following │
       functions, each of which returns the value of the  corresponding	 field │
       listed  in  the	table  below. Note that on some platforms there may be │
       other fields in the Tcl_StatBuf as it is an alias for a suitable system │
       structure, but only the portable ones are made available here. See your │
       system documentation for a full description of these fields.	       │

	      Access Function			 Field			       │
	       Tcl_GetFSDeviceFromStat		  st_dev		       │
	       Tcl_GetFSInodeFromStat		  st_ino		       │
	       Tcl_GetModeFromStat		  st_mode		       │
	       Tcl_GetLinkCountFromStat		  st_nlink		       │
	       Tcl_GetUserIdFromStat		  st_uid		       │
	       Tcl_GetGroupIdFromStat		  st_gid		       │
	       Tcl_GetDeviceTypeFromStat	  st_rdev		       │
	       Tcl_GetAccessTimeFromStat	  st_atime		       │
	       Tcl_GetModificationTimeFromStat	  st_mtime		       │
	       Tcl_GetChangeTimeFromStat	  st_ctime		       │
	       Tcl_GetSizeFromStat		  st_size		       │
	       Tcl_GetBlocksFromStat		  st_blocks		       │
	       Tcl_GetBlockSizeFromStat		  st_blksize		       │


THE VIRTUAL FILESYSTEM API
       A filesystem provides a Tcl_Filesystem structure that contains pointers
       to  functions  that  implement  the various operations on a filesystem;
       these operations are invoked as needed by the generic layer, which gen‐
       erally occurs through the functions listed above.

       The Tcl_Filesystem structures are manipulated using the following meth‐
       ods.

       Tcl_FSRegister takes a pointer to a filesystem  structure  and  an  op‐
       tional  piece  of  data	to associated with that filesystem. On calling
       this function, Tcl will attach the filesystem  to  the  list  of	 known
       filesystems,  and it will become fully functional immediately. Tcl does
       not check if the same filesystem is registered multiple times  (and  in
       general that is not a good thing to do). TCL_OK will be returned.

       Tcl_FSUnregister	 removes  the given filesystem structure from the list
       of known filesystems, if it  is	known,	and  returns  TCL_OK.  If  the
       filesystem is not currently registered, TCL_ERROR is returned.

       Tcl_FSData  will	 return	 the  clientData  associated  with  the	 given
       filesystem, if that filesystem is registered. Otherwise it will	return
       NULL.

       Tcl_FSMountsChanged  is	used  to inform the Tcl's core that the set of
       mount  points  for  the	given  (already	 registered)  filesystem  have
       changed,	 and  that cached file representations may therefore no longer
       be correct.

   THE TCL_FILESYSTEM STRUCTURE
       The Tcl_Filesystem structure contains the following fields:

	      typedef struct Tcl_Filesystem {
		  const char *typeName;
		  int structureLength;
		  Tcl_FSVersion version;
		  Tcl_FSPathInFilesystemProc *pathInFilesystemProc;
		  Tcl_FSDupInternalRepProc *dupInternalRepProc;
		  Tcl_FSFreeInternalRepProc *freeInternalRepProc;
		  Tcl_FSInternalToNormalizedProc *internalToNormalizedProc;
		  Tcl_FSCreateInternalRepProc *createInternalRepProc;
		  Tcl_FSNormalizePathProc *normalizePathProc;
		  Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc;
		  Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc;
		  Tcl_FSStatProc *statProc;
		  Tcl_FSAccessProc *accessProc;
		  Tcl_FSOpenFileChannelProc *openFileChannelProc;
		  Tcl_FSMatchInDirectoryProc *matchInDirectoryProc;
		  Tcl_FSUtimeProc *utimeProc;
		  Tcl_FSLinkProc *linkProc;
		  Tcl_FSListVolumesProc *listVolumesProc;
		  Tcl_FSFileAttrStringsProc *fileAttrStringsProc;
		  Tcl_FSFileAttrsGetProc *fileAttrsGetProc;
		  Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
		  Tcl_FSCreateDirectoryProc *createDirectoryProc;
		  Tcl_FSRemoveDirectoryProc *removeDirectoryProc;
		  Tcl_FSDeleteFileProc *deleteFileProc;
		  Tcl_FSCopyFileProc *copyFileProc;
		  Tcl_FSRenameFileProc *renameFileProc;
		  Tcl_FSCopyDirectoryProc *copyDirectoryProc;
		  Tcl_FSLstatProc *lstatProc;
		  Tcl_FSLoadFileProc *loadFileProc;
		  Tcl_FSGetCwdProc *getCwdProc;
		  Tcl_FSChdirProc *chdirProc;
	      } Tcl_Filesystem;

       Except for the first three fields in this structure which contain  sim‐
       ple data elements, all entries contain addresses of functions called by
       the generic filesystem layer to perform the complete range of  filesys‐
       tem related actions.

       The  many  functions in this structure are broken down into three cate‐
       gories: infrastructure functions (almost all of which  must  be	imple‐
       mented), operational functions (which must be implemented if a complete
       filesystem is provided), and efficiency functions (which need  only  be
       implemented  if	they can be done so efficiently, or if they have side-
       effects which are required by the filesystem; Tcl  has  less  efficient
       emulations  it  can fall back on). It is important to note that, in the
       current version of Tcl, most of these fallbacks are only used to handle
       commands initiated in Tcl, not in C. What this means is, that if a file
       rename command is issued in Tcl, and the relevant filesystem(s) do  not
       implement  their Tcl_FSRenameFileProc, Tcl's core will instead fallback
       on a combination of other filesystem functions (it will use Tcl_FSCopy‐
       FileProc followed by Tcl_FSDeleteFileProc, and if Tcl_FSCopyFileProc is
       not implemented there is a further fallback). However, if  a  Tcl_FSRe‐
       nameFileProc command is issued at the C level, no such fallbacks occur.
       This is true except for the last four entries in the  filesystem	 table
       (lstat, load, getcwd and chdir) for which fallbacks do in fact occur at
       the C level.

       Any functions which take path names in Tcl_Obj form take those names in
       UTF-8  form.  The  filesystem infrastructure API is designed to support
       efficient, cached conversion of these UTF-8 paths to other native  rep‐
       resentations.

   EXAMPLE FILESYSTEM DEFINITION
       Here  is	 the filesystem lookup table used by the “vfs” extension which
       allows filesystem actions to be implemented in Tcl.

	      static Tcl_Filesystem vfsFilesystem = {
		  "tclvfs",
		  sizeof(Tcl_Filesystem),
		  TCL_FILESYSTEM_VERSION_1,
		  &VfsPathInFilesystem,
		  &VfsDupInternalRep,
		  &VfsFreeInternalRep,
		  /* No internal to normalized, since we don't create
		   * any pure 'internal' Tcl_Obj path representations */
		  NULL,
		  /* No create native rep function, since we don't use
		   * it and don't choose to support uses of
		   * Tcl_FSNewNativePath */
		  NULL,
		  /* Normalize path isn't needed - we assume paths only
		   * have one representation */
		  NULL,
		  &VfsFilesystemPathType,
		  &VfsFilesystemSeparator,
		  &VfsStat,
		  &VfsAccess,
		  &VfsOpenFileChannel,
		  &VfsMatchInDirectory,
		  &VfsUtime,
		  /* We choose not to support symbolic links inside our
		   * VFS's */
		  NULL,
		  &VfsListVolumes,
		  &VfsFileAttrStrings,
		  &VfsFileAttrsGet,
		  &VfsFileAttrsSet,
		  &VfsCreateDirectory,
		  &VfsRemoveDirectory,
		  &VfsDeleteFile,
		  /* No copy file; use the core fallback mechanism */
		  NULL,
		  /* No rename file; use the core fallback mechanism */
		  NULL,
		  /* No copy directory; use the core fallback mechanism */
		  NULL,
		  /* Core will use stat for lstat */
		  NULL,
		  /* No load; use the core fallback mechanism */
		  NULL,
		  /* We don't need a getcwd or chdir; the core's own
		   * internal value is suitable */
		  NULL,
		  NULL
	      };

FILESYSTEM INFRASTRUCTURE
       These fields contain basic information about the	 filesystem  structure
       and  addresses  of  functions  which are used to associate a particular
       filesystem with a file path, and deal with  the	internal  handling  of
       path  representations, for example copying and freeing such representa‐
       tions.

   TYPENAME
       The typeName field contains a null-terminated  string  that  identifies
       the type of the filesystem implemented, e.g.  “native”, “zip” or “vfs”.

   STRUCTURE LENGTH
       The    structureLength	 field	  is	generally    implemented    as
       sizeof(Tcl_Filesystem), and is there to allow easier  binary  backwards
       compatibility  if the size of the structure changes in a future Tcl re‐
       lease.

   VERSION
       The version field should be set to TCL_FILESYSTEM_VERSION_1.

   PATHINFILESYSTEMPROC
       The pathInFilesystemProc field contains the address of a function which
       is  called  to  determine  whether  a  given path value belongs to this
       filesystem or not. Tcl will only call the rest of the filesystem	 func‐
       tions  with a path for which this function has returned TCL_OK.	If the
       path does not belong, -1 should be returned (the behavior  of  Tcl  for
       any other return value is not defined). If TCL_OK is returned, then the
       optional clientDataPtr output parameter can be used to return an inter‐
       nal  (filesystem	 specific)  representation  of the path, which will be
       cached inside the path value, and may be retrieved efficiently  by  the
       other filesystem functions. Tcl will simultaneously cache the fact that
       this path belongs to this filesystem. Such caches are invalidated  when
       filesystem  structures are added or removed from Tcl's internal list of
       known filesystems.

	      typedef int Tcl_FSPathInFilesystemProc(
		      Tcl_Obj *pathPtr,
		      ClientData *clientDataPtr);

   DUPINTERNALREPPROC
       This function makes a copy of a path's internal representation, and  is
       called when Tcl needs to duplicate a path value. If NULL, Tcl will sim‐
       ply not copy the internal representation, which may then need to be re‐
       generated later.

	      typedef ClientData Tcl_FSDupInternalRepProc(
		      ClientData clientData);

   FREEINTERNALREPPROC
       Free  the internal representation. This must be implemented if internal
       representations need freeing (i.e. if some memory is allocated when  an
       internal representation is generated), but may otherwise be NULL.

	      typedef void Tcl_FSFreeInternalRepProc(
		      ClientData clientData);

   INTERNALTONORMALIZEDPROC
       Function	 to convert internal representation to a normalized path. Only
       required if the filesystem creates pure path values with no string/path
       representation.	The return value is a Tcl value whose string represen‐
       tation is the normalized path.

	      typedef Tcl_Obj *Tcl_FSInternalToNormalizedProc(
		      ClientData clientData);

   CREATEINTERNALREPPROC
       Function to take a path value, and calculate an internal representation
       for  it, and store that native representation in the value. May be NULL
       if paths have no	 internal  representation,  or	if  the	 Tcl_FSPathIn‐
       FilesystemProc for this filesystem always immediately creates an inter‐
       nal representation for paths it accepts.

	      typedef ClientData Tcl_FSCreateInternalRepProc(
		      Tcl_Obj *pathPtr);

   NORMALIZEPATHPROC
       Function to normalize a path. Should be implemented for all filesystems
       which can have multiple string representations for the same path value.
       In Tcl, every “path” must have a single unique “normalized” string rep‐
       resentation.  Depending	on  the filesystem, there may be more than one
       unnormalized string representation which refers to  that	 path  (e.g. a
       relative	 path,	a path with different character case if the filesystem
       is case insensitive, a path contain a reference	to  a  home  directory
       such  as	 “~”, a path containing symbolic links, etc). If the very last
       component in the path is a symbolic link, it should  not	 be  converted
       into  the  value	 it points to (but its case or other aspects should be
       made unique). All other path components should be converted  from  sym‐
       bolic  links. This one exception is required to agree with Tcl's seman‐
       tics with file delete, file rename, file	 copy  operating  on  symbolic
       links.	This  function may be called with nextCheckpoint either at the
       beginning of the path (i.e. zero), at the end of the path,  or  at  any
       intermediate  file  separator  in  the path. It will never point to any
       other arbitrary position in the path. In the last of  the  three	 valid
       cases,  the implementation can assume that the path up to and including
       the file separator is known and normalized.

	      typedef int Tcl_FSNormalizePathProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      int nextCheckpoint);

FILESYSTEM OPERATIONS
       The fields in this section of the structure contain addresses of	 func‐
       tions  which are called to carry out the basic filesystem operations. A
       filesystem which expects to be used with the complete standard Tcl com‐
       mand  set  must	implement all of these. If some of them are not imple‐
       mented, then certain Tcl commands may  fail  when  operating  on	 paths
       within  that  filesystem. However, in some instances this may be desir‐
       able (for example, a read-only filesystem should not implement the last
       four  functions, and a filesystem which does not support symbolic links
       need not implement the readlink function, etc.  The  Tcl	 core  expects
       filesystems to behave in this way).

   FILESYSTEMPATHTYPEPROC
       Function	 to  determine	the  type of a path in this filesystem. May be
       NULL, in which case no type information will be available to  users  of
       the filesystem. The “type” is used only for informational purposes, and
       should be returned as the string representation of the Tcl_Obj which is
       returned.  A typical return value might be “networked”, “zip” or “ftp”.
       The Tcl_Obj result is owned by the filesystem and so Tcl will increment
       the reference count of that value if it wishes to retain a reference to
       it.

	      typedef Tcl_Obj *Tcl_FSFilesystemPathTypeProc(
		      Tcl_Obj *pathPtr);

   FILESYSTEMSEPARATORPROC
       Function to return the  separator  character(s)	for  this  filesystem.
       This need only be implemented if the filesystem wishes to use a differ‐
       ent separator than the standard string “/”.  Amongst other uses, it  is
       returned	 by  the  file separator command. The return value should be a
       value with reference count of zero.

	      typedef Tcl_Obj *Tcl_FSFilesystemSeparatorProc(
		      Tcl_Obj *pathPtr);

   STATPROC
       Function to process a Tcl_FSStat call. Must be implemented for any rea‐
       sonable filesystem, since many Tcl level commands depend crucially upon
       it (e.g. file atime, file isdirectory, file size, glob).

	      typedef int Tcl_FSStatProc(
		      Tcl_Obj *pathPtr,
		      Tcl_StatBuf *statPtr);

       The Tcl_FSStatProc fills the stat structure  statPtr  with  information
       about the specified file. You do not need any access rights to the file
       to get this information but you need search rights to  all  directories
       named in the path leading to the file. The stat structure includes info
       regarding device, inode (always 0 on Windows),  privilege  mode,	 nlink
       (always	1 on Windows), user id (always 0 on Windows), group id (always
       0 on Windows), rdev (same as device  on	Windows),  size,  last	access
       time, last modification time, and last metadata change time.

       If the file represented by pathPtr exists, the Tcl_FSStatProc returns 0
       and the stat structure is filled with data. Otherwise, -1 is  returned,
       and no stat info is given.

   ACCESSPROC
       Function	 to  process  a Tcl_FSAccess call. Must be implemented for any
       reasonable filesystem, since many Tcl level commands  depend  crucially
       upon it (e.g. file exists, file readable).

	      typedef int Tcl_FSAccessProc(
		      Tcl_Obj *pathPtr,
		      int mode);

       The  Tcl_FSAccessProc  checks  whether  the process would be allowed to
       read, write or test for existence of the file (or other filesystem  ob‐
       ject)  whose  name  is in pathPtr. If the pathname refers to a symbolic
       link, then the permissions of the file referred by this	symbolic  link
       should be tested.

       On  success  (all  requested permissions granted), zero is returned. On
       error (at least one bit in mode asked for a permission that is  denied,
       or some other  error occurred), -1 is returned.

   OPENFILECHANNELPROC
       Function	 to  process a Tcl_FSOpenFileChannel call. Must be implemented
       for any reasonable filesystem, since any operations which require  open
       or  accessing  a	 file's contents will use it (e.g. open, encoding, and
       many Tk commands).

	      typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      int mode,
		      int permissions);

       The Tcl_FSOpenFileChannelProc opens a file specified by pathPtr and re‐
       turns  a channel handle that can be used to perform input and output on
       the file. This API is modeled after the fopen  procedure	 of  the  Unix
       standard	 I/O library. The syntax and meaning of all arguments is simi‐
       lar to those given in the Tcl open command when opening a  file,	 where
       the  mode  argument  is	a  combination	of  the	 POSIX flags O_RDONLY,
       O_WRONLY, etc. If an  error  occurs  while  opening  the	 channel,  the
       Tcl_FSOpenFileChannelProc  returns  NULL and records a POSIX error code
       that can be retrieved with Tcl_GetErrno.	 In  addition,	if  interp  is
       non-NULL,  the Tcl_FSOpenFileChannelProc leaves an error message in in‐
       terp's result after any error.

       The newly created channel must not be registered in the supplied inter‐
       preter by a Tcl_FSOpenFileChannelProc; that task is up to the caller of
       Tcl_FSOpenFileChannel (if necessary). If one of the standard  channels,
       stdin,  stdout or stderr was previously closed, the act of creating the
       new channel also assigns it as a replacement for the standard channel.

   MATCHINDIRECTORYPROC
       Function to process a Tcl_FSMatchInDirectory call. If not  implemented,
       then  glob  and	recursive  copy	 functionality	will be lacking in the
       filesystem (and this may impact commands like encoding names which  use
       glob functionality internally).

	      typedef int Tcl_FSMatchInDirectoryProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *resultPtr,
		      Tcl_Obj *pathPtr,
		      const char *pattern,
		      Tcl_GlobTypeData *types);

       The  function should return all files or directories (or other filesys‐
       tem objects) which match the given pattern and accord  with  the	 types
       specification  given.  There are two ways in which this function may be
       called. If pattern is NULL, then pathPtr is a full  path	 specification
       of a single file or directory which should be checked for existence and
       correct type. Otherwise, pathPtr is a directory, the contents of	 which
       the function should search for files or directories which have the cor‐
       rect type. In either case, pathPtr can be assumed to be	both  non-NULL
       and non-empty. It is not currently documented whether pathPtr will have
       a file separator at its end of not, so code should be flexible to  both
       possibilities.

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the matching process. Error messages are placed in  interp,
       unless interp in NULL in which case no error message need be generated;
       on a TCL_OK result, results should be  added  to	 the  resultPtr	 value
       given  (which  can  be  assumed	to  be a valid unshared Tcl list). The
       matches added to resultPtr should include  any  path  prefix  given  in
       pathPtr (this usually means they will be absolute path specifications).
       Note that if no matches are found, that simply leads to	an  empty  re‐
       sult;  errors  are only signaled for actual file or filesystem problems
       which may occur during the matching process.

       The Tcl_GlobTypeData structure passed in the types  parameter  contains
       the following fields:

	      typedef struct Tcl_GlobTypeData {
		  /* Corresponds to bcdpfls as in 'find -t' */
		  int type;
		  /* Corresponds to file permissions */
		  int perm;
		  /* Acceptable mac type */
		  Tcl_Obj *macType;
		  /* Acceptable mac creator */
		  Tcl_Obj *macCreator;
	      } Tcl_GlobTypeData;

       There are two specific cases which it is important to handle correctly,
       both when types is non-NULL. The two  cases  are	 when  types->types  &
       TCL_GLOB_TYPE_DIR  or  types->types & TCL_GLOB_TYPE_MOUNT are true (and
       in particular when the other flags are false). In the  first  of	 these
       cases,  the function must list the contained directories. Tcl uses this
       to implement recursive globbing, so it is critical that filesystems im‐
       plement	directory  matching  correctly.	 In the second of these cases,
       with TCL_GLOB_TYPE_MOUNT, the filesystem must  list  the	 mount	points
       which  lie within the given pathPtr (and in this case, pathPtr need not
       lie within the same filesystem - different to all other cases in	 which
       this  function  is  called).  Support for this is critical if Tcl is to
       have seamless transitions between from one filesystem to another.

   UTIMEPROC
       Function to process a Tcl_FSUtime call. Required to allow setting  (not
       reading)	 of  times  with  file	mtime, file atime and the open-r/open-
       w/fcopy implementation of file copy.

	      typedef int Tcl_FSUtimeProc(
		      Tcl_Obj *pathPtr,
		      struct utimbuf *tval);

       The access and modification times of  the  file	specified  by  pathPtr
       should be changed to the values given in the tval structure.

       The return value should be 0 on success and -1 on an error, as with the
       system utime.

   LINKPROC
       Function to process a Tcl_FSLink call. Should be	 implemented  only  if
       the filesystem supports links, and may otherwise be NULL.

	      typedef Tcl_Obj *Tcl_FSLinkProc(
		      Tcl_Obj *linkNamePtr,
		      Tcl_Obj *toPtr,
		      int linkAction);

       If toPtr is NULL, the function is being asked to read the contents of a
       link. The result is a Tcl_Obj specifying the contents of the link given
       by  linkNamePtr,	 or  NULL if the link could not be read. The result is
       owned by the caller (and should therefore have  its  ref	 count	incre‐
       mented before being returned). Any callers should call Tcl_DecrRefCount
       on this result when it is no longer needed.  If toPtr is not NULL,  the
       function	 should	 attempt  to  create  a link.  The result in this case
       should be toPtr if the link was successful and NULL otherwise. In  this
       case the result is not owned by the caller (i.e. no reference count ma‐
       nipulations on either  end  are	needed).  See  the  documentation  for
       Tcl_FSLink for the correct interpretation of the linkAction flags.

   LISTVOLUMESPROC
       Function	 to  list  any	filesystem  volumes  added by this filesystem.
       Should be implemented only if the filesystem adds volumes at  the  head
       of the filesystem, so that they can be returned by file volumes.

	      typedef Tcl_Obj *Tcl_FSListVolumesProc(void);

       The  result  should  be	a list of volumes added by this filesystem, or
       NULL (or an empty list) if no volumes are provided. The result value is
       considered  to  be  owned  by  the  filesystem (not by Tcl's core), but
       should be given a reference count for Tcl. Tcl will use the contents of
       the  list and then decrement that reference count. This allows filesys‐
       tems to choose whether they actually want to retain a “global list”  of
       volumes	or  not (if not, they generate the list on the fly and pass it
       to Tcl with a reference count of 1 and then forget about the  list,  if
       yes,  then  they	 simply	 increment the reference count of their global
       list and pass it to Tcl which will copy the contents and then decrement
       the count back to where it was).

       Therefore, Tcl considers return values from this proc to be read-only.

   FILEATTRSTRINGSPROC
       Function	 to  list  all	attribute  strings  which  are	valid for this
       filesystem. If not implemented the filesystem will not support the file
       attributes  command. This allows arbitrary additional information to be
       attached to files in the filesystem. If it is not implemented, there is
       no need to implement the get and set methods.

	      typedef const char *const *Tcl_FSFileAttrStringsProc(
		      Tcl_Obj *pathPtr,
		      Tcl_Obj **objPtrRef);

       The  called  function may either return an array of strings, or may in‐
       stead return NULL and place a Tcl list into the	given  objPtrRef.  Tcl
       will  take that list and first increment its reference count before us‐
       ing it.	On completion of that use, Tcl will  decrement	its  reference
       count.  Hence  if  the  list should be disposed of by Tcl when done, it
       should have a reference count of zero, and if the list  should  not  be
       disposed	 of,  the  filesystem  should ensure it returns a value with a
       reference count of at least one.

   FILEATTRSGETPROC
       Function to process a Tcl_FSFileAttrsGet call, used by file attributes.

	      typedef int Tcl_FSFileAttrsGetProc(
		      Tcl_Interp *interp,
		      int index,
		      Tcl_Obj *pathPtr,
		      Tcl_Obj **objPtrRef);

       Returns a standard Tcl return  code.  The  attribute  value  retrieved,
       which  corresponds  to the index'th element in the list returned by the
       Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if	TCL_OK
       was  returned)  and is likely to have a reference count of zero. Either
       way we must  either  store  it  somewhere  (e.g. the  Tcl  result),  or
       Incr/Decr its reference count to ensure it is properly freed.

   FILEATTRSSETPROC
       Function to process a Tcl_FSFileAttrsSet call, used by file attributes.
       If the filesystem is read-only, there is no need to implement this.

	      typedef int Tcl_FSFileAttrsSetProc(
		      Tcl_Interp *interp,
		      int index,
		      Tcl_Obj *pathPtr,
		      Tcl_Obj *objPtr);

       The attribute value of the index'th element in the list returned by the
       Tcl_FSFileAttrStringsProc should be set to the objPtr given.

   CREATEDIRECTORYPROC
       Function to process a Tcl_FSCreateDirectory call. Should be implemented
       unless the FS is read-only.

	      typedef int Tcl_FSCreateDirectoryProc(
		      Tcl_Obj *pathPtr);

       The return value is a standard Tcl result indicating whether  an	 error
       occurred	 in  the  process.  If successful, a new directory should have
       been added to the filesystem in the location specified by pathPtr.

   REMOVEDIRECTORYPROC
       Function to process a Tcl_FSRemoveDirectory call. Should be implemented
       unless the FS is read-only.

	      typedef int Tcl_FSRemoveDirectoryProc(
		      Tcl_Obj *pathPtr,
		      int recursive,
		      Tcl_Obj **errorPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the process. If  successful,	 the  directory	 specified  by
       pathPtr	should have been removed from the filesystem. If the recursive
       flag is given, then a non-empty directory should be deleted without er‐
       ror.  If	 this flag is not given, then and the directory is non-empty a
       POSIX “EEXIST” error should be signaled. If an error  does  occur,  the
       name  of	 the file or directory which caused the error should be placed
       in errorPtr.

   DELETEFILEPROC
       Function to process a Tcl_FSDeleteFile call. Should be implemented  un‐
       less the FS is read-only.

	      typedef int Tcl_FSDeleteFileProc(
		      Tcl_Obj *pathPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the process. If successful, the file specified  by  pathPtr
       should  have  been  removed  from  the  filesystem.  Note  that, if the
       filesystem supports symbolic links, Tcl will always call this  function
       and  not	 Tcl_FSRemoveDirectoryProc when needed to delete them (even if
       they are symbolic links to directories).

FILESYSTEM EFFICIENCY
       These functions need not be implemented for a particular filesystem be‐
       cause  the core has a fallback implementation available. See each indi‐
       vidual description for the consequences of leaving the field NULL.

   LSTATPROC
       Function to process a Tcl_FSLstat call. If not  implemented,  Tcl  will
       attempt	to  use	 the statProc defined above instead. Therefore it need
       only be implemented if a filesystem can differentiate between stat  and
       lstat calls.

	      typedef int Tcl_FSLstatProc(
		      Tcl_Obj *pathPtr,
		      Tcl_StatBuf *statPtr);

       The  behavior  of  this	function  is  very  similar  to	 that  of  the
       Tcl_FSStatProc defined above, except that if it is applied  to  a  sym‐
       bolic link, it returns information about the link, not about the target
       file.

   COPYFILEPROC
       Function to process a Tcl_FSCopyFile call. If not implemented Tcl  will
       fall  back  on open-r, open-w and fcopy as a copying mechanism.	There‐
       fore it need only be implemented if the filesystem can perform that ac‐
       tion more efficiently.

	      typedef int Tcl_FSCopyFileProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the copying process. Note that, destPathPtr is the name  of
       the  file  which	 should become the copy of srcPathPtr. It is never the
       name of a directory into which srcPathPtr  could	 be  copied  (i.e. the
       function is much simpler than the Tcl level file copy subcommand). Note
       that, if the filesystem supports symbolic links, Tcl will  always  call
       this  function and not copyDirectoryProc when needed to copy them (even
       if they are symbolic links to directories). Finally, if the  filesystem
       determines  it  cannot support the file copy action, calling Tcl_SetEr‐
       rno(EXDEV) and returning a non-TCL_OK result will tell Tcl to  use  its
       standard fallback mechanisms.

   RENAMEFILEPROC
       Function	 to  process  a Tcl_FSRenameFile call. If not implemented, Tcl
       will fall back on a copy and delete mechanism. Therefore it  need  only
       be  implemented	if  the	 filesystem can perform that action more effi‐
       ciently.

	      typedef int Tcl_FSRenameFileProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr);

       The return value is a standard Tcl result indicating whether  an	 error
       occurred	 in the renaming process. If the filesystem determines it can‐
       not support the file rename action, calling Tcl_SetErrno(EXDEV) and re‐
       turning	a non-TCL_OK result will tell Tcl to use its standard fallback
       mechanisms.

   COPYDIRECTORYPROC
       Function to process a Tcl_FSCopyDirectory call. If not implemented, Tcl
       will  fall  back on a recursive file mkdir, file copy mechanism. There‐
       fore it need only be implemented if the filesystem can perform that ac‐
       tion more efficiently.

	      typedef int Tcl_FSCopyDirectoryProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr,
		      Tcl_Obj **errorPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the copying process. If an error does occur,	 the  name  of
       the  file  or  directory which caused the error should be placed in er‐
       rorPtr. Note that, destPathPtr is the name of the directory-name	 which
       should  become  the mirror-image of srcPathPtr. It is not the name of a
       directory into which srcPathPtr should be copied (i.e. the function  is
       much  simpler than the Tcl level file copy subcommand). Finally, if the
       filesystem determines it cannot	support	 the  directory	 copy  action,
       calling Tcl_SetErrno(EXDEV) and returning a non-TCL_OK result will tell
       Tcl to use its standard fallback mechanisms.

   LOADFILEPROC
       Function to process a Tcl_FSLoadFile call. If not implemented, Tcl will
       fall back on a copy to native-temp followed by a Tcl_FSLoadFile on that
       temporary copy. Therefore it need only be implemented if the filesystem
       can  load  code	directly,  or  it  can be implemented simply to return
       TCL_ERROR to disable load functionality in this filesystem entirely.

	      typedef int Tcl_FSLoadFileProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      Tcl_LoadHandle *handlePtr,
		      Tcl_FSUnloadFileProc *unloadProcPtr);

       Returns a standard Tcl completion code. If an error  occurs,  an	 error
       message	is left in the interp's result. The function dynamically loads
       a binary code file into memory. On a  successful	 load,	the  handlePtr
       should  be filled with a token for the dynamically loaded file, and the
       unloadProcPtr should be filled in with the address of a procedure.  The
       unload  procedure  will	be called with the given Tcl_LoadHandle as its
       only parameter when Tcl needs to unload the file. For example, for  the
       native  filesystem,  the	 Tcl_LoadHandle	 returned is currently a token
       which can be used in the private TclpFindSymbol to access functions  in
       the  new	 code. Each filesystem is free to define the Tcl_LoadHandle as
       it requires. Finally, if the filesystem determines  it  cannot  support
       the  file load action, calling Tcl_SetErrno(EXDEV) and returning a non-
       TCL_OK result will tell Tcl to use its standard fallback mechanisms.

   UNLOADFILEPROC
       Function to unload a previously successfully loaded file. If  load  was
       implemented,  then  this	 should	 also  be implemented, if there is any
       cleanup action required.

	      typedef void Tcl_FSUnloadFileProc(
		      Tcl_LoadHandle loadHandle);

   GETCWDPROC
       Function to process a Tcl_FSGetCwd call. Most filesystems need not  im‐
       plement	this. It will usually only be called once, if getcwd is called
       before chdir. May be NULL.

	      typedef Tcl_Obj *Tcl_FSGetCwdProc(
		      Tcl_Interp *interp);

       If the filesystem supports a native notion of a current working	direc‐
       tory  (which  might  perhaps  change independent of Tcl), this function
       should return that cwd as the result, or NULL if the current  directory
       could  not  be determined (e.g. the user does not have appropriate per‐
       missions on the cwd directory). If NULL is returned, an	error  message
       is left in the interp's result.

   CHDIRPROC
       Function to process a Tcl_FSChdir call. If filesystems do not implement
       this, it will be emulated by a series of directory access checks.  Oth‐
       erwise,	virtual	 filesystems  which  do implement it need only respond
       with a positive return result if the pathPtr is a valid, accessible di‐
       rectory	in  their filesystem. They need not remember the result, since
       that will be automatically remembered for use  by  Tcl_FSGetCwd.	  Real
       filesystems  should carry out the correct action (i.e. call the correct
       system chdir API).

	      typedef int Tcl_FSChdirProc(
		      Tcl_Obj *pathPtr);

       The Tcl_FSChdirProc changes the applications current working  directory
       to  the value specified in pathPtr. The function returns -1 on error or
       0 on success.

SEE ALSO
       cd(n), file(n), filename(n), load(n), open(n), pwd(n),  source(n),  un‐
       load(n)

KEYWORDS
       stat, access, filesystem, vfs, virtual filesystem



Tcl				      8.4			 Filesystem(3)

Tcl_SetResult(3)	    Tcl Library Procedures	      Tcl_SetResult(3)



______________________________________________________________________________

NAME
       Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult,
       Tcl_AppendResult, Tcl_AppendResultVA,  Tcl_AppendElement,  Tcl_ResetRe‐
       sult, Tcl_TransferResult, Tcl_FreeResult - manipulate Tcl result

SYNOPSIS
       #include <tcl.h>

       Tcl_SetObjResult(interp, objPtr)

       Tcl_Obj *
       Tcl_GetObjResult(interp)

       Tcl_SetResult(interp, result, freeProc)

       const char *
       Tcl_GetStringResult(interp)

       Tcl_AppendResult(interp, result, result, ... , (char *)NULL)

       Tcl_AppendResultVA(interp, argList)

       Tcl_ResetResult(interp)

       Tcl_TransferResult(sourceInterp, code, targetInterp)		       │

       Tcl_AppendElement(interp, element)

       Tcl_FreeResult(interp)

ARGUMENTS
       Tcl_Interp *interp (out)		       Interpreter  whose result is to
					       be modified or read.

       Tcl_Obj *objPtr (in)		       Tcl value to become result  for
					       interp.

       char *result (in)		       String  value  to become result
					       for interp or to be appended to
					       the existing result.

       const char *element (in)		       String  value  to  append  as a
					       list element  to	 the  existing
					       result of interp.

       Tcl_FreeProc *freeProc (in)	       Address of procedure to call to
					       release storage at  result,  or
					       TCL_STATIC,   TCL_DYNAMIC,   or
					       TCL_VOLATILE.

       va_list argList (in)		       An  argument  list  which  must
					       have   been  initialized	 using
					       va_start,  and  cleared	 using
					       va_end.

       Tcl_Interp *sourceInterp (in)	       Interpreter that the result and │
					       return options should be trans‐ │
					       ferred from.

       Tcl_Interp *targetInterp (in)	       Interpreter that the result and │
					       return options should be trans‐ │
					       ferred to.

       int code (in)			       Return code value that controls │
					       transfer of return options.
______________________________________________________________________________

DESCRIPTION
       The procedures described here are utilities for manipulating the result
       value in a Tcl interpreter.  The interpreter result may be either a Tcl
       value or a string.  For example, Tcl_SetObjResult and Tcl_SetResult set
       the  interpreter	 result to, respectively, a value and a string.	 Simi‐
       larly, Tcl_GetObjResult and Tcl_GetStringResult return the  interpreter
       result  as  a  value  and  as a string.	The procedures always keep the
       string and value forms of the interpreter result consistent.  For exam‐
       ple,  if	 Tcl_SetObjResult is called to set the result to a value, then
       Tcl_GetStringResult is called, it will return the value's string repre‐
       sentation.

       Tcl_SetObjResult	 arranges  for objPtr to be the result for interp, re‐
       placing any existing result.  The result is left pointing to the	 value
       referenced  by  objPtr.	 objPtr's reference count is incremented since
       there is now a new reference to it from interp.	 The  reference	 count
       for  any	 old  result  value is decremented and the old result value is
       freed if no references to it remain.

       Tcl_GetObjResult returns the result for interp as a value.  The value's
       reference  count	 is  not  incremented; if the caller needs to retain a
       long-term pointer to the value they should use Tcl_IncrRefCount to  in‐
       crement	its  reference	count in order to keep it from being freed too
       early or accidentally changed.

       Tcl_SetResult arranges for result to be the result for the current  Tcl
       command	in  interp, replacing any existing result.  The freeProc argu‐
       ment specifies how to manage the storage for the result argument; it is
       discussed in the section THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT be‐
       low.  If result is NULL, then freeProc is ignored and Tcl_SetResult re-
       initializes interp's result to point to an empty string.

       Tcl_GetStringResult  returns the result for interp as a string.	If the
       result was set to a value by a Tcl_SetObjResult call,  the  value  form
       will be converted to a string and returned.  If the value's string rep‐
       resentation contains null bytes, this conversion will lose information.
       For  this reason, programmers are encouraged to write their code to use
       the new value API procedures and to call Tcl_GetObjResult instead.

       Tcl_ResetResult clears the result for interp and leaves the  result  in
       its normal empty initialized state.  If the result is a value, its ref‐
       erence count is decremented and the result is left pointing to  an  un‐
       shared  value representing an empty string.  If the result is a dynami‐
       cally allocated string, its memory is free*d and the result is left  as
       a empty string.	Tcl_ResetResult also clears the error state managed by
       Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, and Tcl_SetErrorCode.

       Tcl_AppendResult makes it easy to build up Tcl results in  pieces.   It
       takes  each  of	its  result arguments and appends them in order to the
       current result associated with interp.  If the result is	 in  its  ini‐
       tialized	 empty	state  (e.g.  a	 command procedure was just invoked or
       Tcl_ResetResult was just called), then Tcl_AppendResult sets the result
       to  the concatenation of its result arguments.  Tcl_AppendResult may be
       called repeatedly as additional pieces  of  the	result	are  produced.
       Tcl_AppendResult	 takes care of all the storage management issues asso‐
       ciated with managing interp's result, such as allocating a  larger  re‐
       sult area if necessary.	It also manages conversion to and from the re‐
       sult field of the interp so as to  handle  backward-compatibility  with
       old-style  extensions.  Any number of result arguments may be passed in
       a single call; the last argument in the list must be (char *)NULL.

       Tcl_AppendResultVA is the same as Tcl_AppendResult except that  instead
       of taking a variable number of arguments it takes an argument list.

       Tcl_TransferResult  transfers  interpreter  state  from sourceInterp to │
       targetInterp. The two interpreters must have been created in  the  same │
       thread.	 If  sourceInterp  and	targetInterp  are the same, nothing is │
       done. Otherwise, Tcl_TransferResult moves the result from  sourceInterp │
       to  targetInterp,  and resets the result in sourceInterp. It also moves │
       the return options dictionary as controlled by the  return  code	 value │
       code in the same manner as Tcl_GetReturnOptions.

DEPRECATED INTERFACES
   OLD STRING PROCEDURES
       Use of the following procedures is deprecated since they manipulate the
       Tcl result as a string.	Procedures such as Tcl_SetObjResult  that  ma‐
       nipulate the result as a value can be significantly more efficient.

       Tcl_AppendElement  is similar to Tcl_AppendResult in that it allows re‐
       sults to be built up in pieces.	However, Tcl_AppendElement takes  only
       a  single  element argument and it appends that argument to the current
       result as a proper Tcl  list  element.	Tcl_AppendElement  adds	 back‐
       slashes	or  braces  if necessary to ensure that interp's result can be
       parsed as a list and that element will be extracted as  a  single  ele‐
       ment.   Under  normal  conditions,  Tcl_AppendElement  will add a space
       character to interp's result just before adding the new	list  element,
       so  that	 the list elements in the result are properly separated.  How‐
       ever if the new list element is the first in a list or  sub-list	 (i.e.
       interp's	 current  result is empty, or consists of the single character
       “{”, or ends in the characters “ {”) then no space is added.

       Tcl_FreeResult performs part of the work of Tcl_ResetResult.  It	 frees
       up  the	memory	associated  with  interp's  result.   It also sets in‐
       terp->freeProc to zero, but does not change interp->result or clear er‐
       ror  state.   Tcl_FreeResult  is most commonly used when a procedure is
       about to replace one result value with another.

   DIRECT ACCESS TO INTERP->RESULT
       It used to be legal for programs to directly read and write interp->re‐
       sult  to	 manipulate the interpreter result.  The Tcl headers no longer
       permit this access by default, and C code still doing this must be  up‐
       dated  to use supported routines Tcl_GetObjResult, Tcl_GetStringResult,
       Tcl_SetObjResult, and Tcl_SetResult.  As a migration aid, access can be
       restored with the compiler directive
	      #define USE_INTERP_RESULT
       but this is meant only to offer life support to otherwise dead code.

THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT
       Tcl_SetResult's	freeProc  argument  specifies how the Tcl system is to
       manage the storage  for	the  result  argument.	 If  Tcl_SetResult  or
       Tcl_SetObjResult	 are  called  at a time when interp holds a string re‐
       sult, they do whatever is necessary to dispose of the old string result
       (see the Tcl_Interp manual entry for details on this).

       If  freeProc  is	 TCL_STATIC  it means that result refers to an area of
       static storage that is guaranteed not to be modified until at least the
       next call to Tcl_Eval.  If freeProc is TCL_DYNAMIC it means that result
       was allocated with a call to Tcl_Alloc and is now the property  of  the
       Tcl  system.  Tcl_SetResult will arrange for the string's storage to be
       released by calling Tcl_Free when it is no longer needed.  If  freeProc
       is  TCL_VOLATILE	 it means that result points to an area of memory that
       is likely to be overwritten when Tcl_SetResult returns (e.g. it	points
       to something in a stack frame).	In this case Tcl_SetResult will make a
       copy of the string in dynamically allocated storage and arrange for the
       copy to be the result for the current Tcl command.

       If  freeProc  is	 not  one  of  the values TCL_STATIC, TCL_DYNAMIC, and
       TCL_VOLATILE, then it is the address of a  procedure  that  Tcl	should
       call  to free the string.  This allows applications to use non-standard
       storage allocators.  When Tcl no	 longer	 needs	the  storage  for  the
       string,	it  will call freeProc. FreeProc should have arguments and re‐
       sult that match the type Tcl_FreeProc:

	      typedef void Tcl_FreeProc(
		      char *blockPtr);

       When freeProc is called, its blockPtr will be set to the value  of  re‐
       sult passed to Tcl_SetResult.

SEE ALSO
       Tcl_AddErrorInfo,  Tcl_CreateObjCommand,	 Tcl_SetErrorCode, Tcl_Interp,
       Tcl_GetReturnOptions

KEYWORDS
       append, command, element, list, value,  result,	return	value,	inter‐
       preter



Tcl				      8.6		      Tcl_SetResult(3)

Tcl_IntObj(3)		    Tcl Library Procedures		 Tcl_IntObj(3)



______________________________________________________________________________

NAME
       Tcl_NewIntObj,	 Tcl_NewLongObj,   Tcl_NewWideIntObj,	Tcl_SetIntObj,
       Tcl_SetLongObj, Tcl_SetWideIntObj,  Tcl_GetIntFromObj,  Tcl_GetLongFro‐
       mObj,	Tcl_GetWideIntFromObj,	 Tcl_NewBignumObj,   Tcl_SetBignumObj,
       Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj - manipulate Tcl values  as
       integers

SYNOPSIS
       #include <tcl.h>

       Tcl_Obj *
       Tcl_NewIntObj(intValue)

       Tcl_Obj *
       Tcl_NewLongObj(longValue)

       Tcl_Obj *
       Tcl_NewWideIntObj(wideValue)

       Tcl_SetIntObj(objPtr, intValue)

       Tcl_SetLongObj(objPtr, longValue)

       Tcl_SetWideIntObj(objPtr, wideValue)

       int
       Tcl_GetIntFromObj(interp, objPtr, intPtr)

       int
       Tcl_GetLongFromObj(interp, objPtr, longPtr)

       int
       Tcl_GetWideIntFromObj(interp, objPtr, widePtr)


       #include <tclTomMath.h>

       Tcl_Obj *
       Tcl_NewBignumObj(bigValue)

       Tcl_SetBignumObj(objPtr, bigValue)

       int
       Tcl_GetBignumFromObj(interp, objPtr, bigValue)

       int
       Tcl_TakeBignumFromObj(interp, objPtr, bigValue)

       int
       Tcl_InitBignumFromDouble(interp, doubleValue, bigValue)

ARGUMENTS
       int intValue (in)		     Integer  value used to initialize
					     or set a Tcl value.

       long longValue (in)		     Long integer value used  to  ini‐
					     tialize or set a Tcl value.

       Tcl_WideInt wideValue (in)	     Wide  integer  value used to ini‐
					     tialize or set a Tcl value.

       Tcl_Obj *objPtr (in/out)		     For  Tcl_SetIntObj,   Tcl_SetLon‐
					     gObj,    Tcl_SetWideIntObj,   and
					     Tcl_SetBignumObj, this points  to
					     the  value	 in  which to store an
					     integral value.  For  Tcl_GetInt‐
					     FromObj,	   Tcl_GetLongFromObj,
					     Tcl_GetWideIntFromObj,   Tcl_Get‐
					     BignumFromObj,    and   Tcl_Take‐
					     BignumFromObj, this refers to the
					     value  from  which to retrieve an
					     integral value.

       Tcl_Interp *interp (in/out)	     When non-NULL, an	error  message
					     is	 left here when integral value
					     retrieval fails.

       int *intPtr (out)		     Points to place to store the  in‐
					     teger  value  retrieved  from ob‐
					     jPtr.

       long *longPtr (out)		     Points to place to store the long
					     integer  value retrieved from ob‐
					     jPtr.

       Tcl_WideInt *widePtr (out)	     Points to place to store the wide
					     integer  value retrieved from ob‐
					     jPtr.

       mp_int *bigValue (in/out)	     Points to a multi-precision inte‐
					     ger  structure  declared  by  the
					     LibTomMath library.

       double doubleValue (in)		     Double value from which the inte‐
					     ger  part	is determined and used
					     to initialize  a  multi-precision
					     integer value.
______________________________________________________________________________

DESCRIPTION
       These  procedures  are used to create, modify, and read Tcl values that
       hold integral values.

       The different routines exist to accommodate different integral types in
       C with which values might be exchanged.	The C integral types for which
       Tcl provides value exchange routines are int,  long  int,  Tcl_WideInt,
       and  mp_int.  The int and long int types are provided by the C language
       standard.  The Tcl_WideInt type is a typedef  defined  to  be  whatever
       signed	integral  type	covers	at  least  the	64-bit	integer	 range
       (-9223372036854775808 to 9223372036854775807).  Depending on the	 plat‐
       form  and  the C compiler, the actual type might be long int, long long
       int, __int64, or something else.	 The mp_int type is a  multiple-preci‐
       sion  integer type defined by the LibTomMath multiple-precision integer
       library.

       The Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, and Tcl_NewBignu‐
       mObj routines each create and return a new Tcl value initialized to the
       integral value of the argument.	The returned Tcl value is unshared.

       The Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, and Tcl_SetBignu‐
       mObj routines each set the value of an existing Tcl value pointed to by
       objPtr to the integral value provided by the other argument.   The  ob‐
       jPtr  argument must point to an unshared Tcl value.  Any attempt to set
       the value of a shared Tcl value violates	 Tcl's	copy-on-write  policy.
       Any  existing  string  representation or internal representation in the
       unshared Tcl value will be freed as a consequence of  setting  the  new
       value.

       The   Tcl_GetIntFromObj,	  Tcl_GetLongFromObj,	Tcl_GetWideIntFromObj,
       Tcl_GetBignumFromObj, and Tcl_TakeBignumFromObj routines attempt to re‐
       trieve an integral value of the appropriate type from the Tcl value ob‐
       jPtr.  If the attempt succeeds, then TCL_OK is returned, and the	 value
       is  written  to	the storage provided by the caller.  The attempt might
       fail if objPtr does not hold an integral value, or if the value exceeds
       the  range of the target type.  If the attempt fails, then TCL_ERROR is
       returned, and if interp is non-NULL, an error message is	 left  in  in‐
       terp.   The  Tcl_ObjType	 of  objPtr  may be changed to make subsequent
       calls to the same routine more efficient. Unlike the  other  functions,
       Tcl_TakeBignumFromObj may set the content of the Tcl value objPtr to an
       empty string in the process of retrieving the multiple-precision	 inte‐
       ger value.

       The  choice  between  Tcl_GetBignumFromObj and Tcl_TakeBignumFromObj is
       governed by how the caller will continue to use objPtr.	If  after  the
       mp_int value is retrieved from objPtr, the caller will make no more use
       of objPtr, then using Tcl_TakeBignumFromObj permits Tcl to detect  when
       an  unshared  objPtr  permits  the value to be moved instead of copied,
       which should be more efficient.	If anything later in  the  caller  re‐
       quires  objPtr  to continue to hold the same value, then Tcl_GetBignum‐
       FromObj must be chosen.

       The Tcl_InitBignumFromDouble routine is a utility  procedure  that  ex‐
       tracts the integer part of doubleValue and stores that integer value in
       the mp_int value bigValue.

SEE ALSO
       Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult

KEYWORDS
       integer, integer value, integer type, internal  representation,	value,
       value type, string representation



Tcl				      8.5			 Tcl_IntObj(3)

Tcl_Eval(3)		    Tcl Library Procedures		   Tcl_Eval(3)



______________________________________________________________________________

NAME
       Tcl_EvalObjEx,	Tcl_EvalFile,	Tcl_EvalObjv,	Tcl_Eval,  Tcl_EvalEx,
       Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA - execute
       Tcl scripts

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_EvalObjEx(interp, objPtr, flags)

       int
       Tcl_EvalFile(interp, fileName)

       int
       Tcl_EvalObjv(interp, objc, objv, flags)

       int
       Tcl_Eval(interp, script)

       int
       Tcl_EvalEx(interp, script, numBytes, flags)

       int
       Tcl_GlobalEval(interp, script)

       int
       Tcl_GlobalEvalObj(interp, objPtr)

       int
       Tcl_VarEval(interp, part, part, ... (char *)NULL)

       int
       Tcl_VarEvalVA(interp, argList)

ARGUMENTS
       Tcl_Interp *interp (in)		  Interpreter  in which to execute the
					  script.  The interpreter's result is
					  modified to hold the result or error
					  message from the script.

       Tcl_Obj *objPtr (in)		  A Tcl value containing the script to
					  execute.

       int flags (in)			  OR'ed	 combination of flag bits that
					  specify     additional      options.
					  TCL_EVAL_GLOBAL  and TCL_EVAL_DIRECT
					  are currently supported.

       const char *fileName (in)	  Name of  a  file  containing	a  Tcl
					  script.

       int objc (in)			  The  number  of  values in the array
					  pointed to by objv; this is also the
					  number of words in the command.

       Tcl_Obj **objv (in)		  Points  to  an  array of pointers to
					  values; each value holds  the	 value
					  of  a	 single word in the command to
					  execute.

       int numBytes (in)		  The number of bytes in  script,  not
					  including any null terminating char‐
					  acter.  If -1, then  all  characters
					  up to the first null byte are used.

       const char *script (in)		  Points  to  first  byte of script to
					  execute (null-terminated and UTF-8).

       const char *part (in)		  String forming part of a Tcl script.

       va_list argList (in)		  An argument  list  which  must  have
					  been initialized using va_start, and
					  cleared using va_end.
______________________________________________________________________________


DESCRIPTION
       The procedures described here are invoked to  execute  Tcl  scripts  in
       various forms.  Tcl_EvalObjEx is the core procedure and is used by many
       of the others.  It executes the commands in the script stored in objPtr
       until  either  an error occurs or the end of the script is reached.  If
       this is the first time objPtr has been executed, its commands are  com‐
       piled  into  bytecode  instructions which are then executed.  The byte‐
       codes are saved in objPtr so that the compilation step can  be  skipped
       if the value is evaluated again in the future.

       The  return  value from Tcl_EvalObjEx (and all the other procedures de‐
       scribed here) is a Tcl completion code with one of the  values  TCL_OK,
       TCL_ERROR,  TCL_RETURN,	TCL_BREAK,  or	TCL_CONTINUE, or possibly some
       other integer value originating in an extension.	 In addition, a result
       value  or error message is left in interp's result; it can be retrieved
       using Tcl_GetObjResult.

       Tcl_EvalFile reads the file given by fileName and  evaluates  its  con‐
       tents  as a Tcl script.	It returns the same information as Tcl_EvalOb‐
       jEx.  If the file could not be read then a Tcl error is returned to de‐
       scribe  why the file could not be read.	The eofchar for files is “\32”
       (^Z) for all platforms. If you require a “^Z” in code for  string  com‐
       parison,	 you  can use “\032” or “\u001a”, which will be safely substi‐
       tuted by the Tcl interpreter into “^Z”.

       Tcl_EvalObjv executes a single preparsed command instead of  a  script.
       The objc and objv arguments contain the values of the words for the Tcl
       command, one word in each value in objv.	  Tcl_EvalObjv	evaluates  the
       command	and returns a completion code and result just like Tcl_EvalOb‐
       jEx.  The caller of Tcl_EvalObjv has to manage the reference  count  of
       the  elements  of  objv,	 insuring  that	 the  values  are  valid until
       Tcl_EvalObjv returns.

       Tcl_Eval is similar to Tcl_EvalObjEx except that the script to be  exe‐
       cuted is supplied as a string instead of a value and no compilation oc‐
       curs.  The string should be a  proper  UTF-8  string  as	 converted  by
       Tcl_ExternalToUtfDString	 or Tcl_ExternalToUtf when it is known to pos‐
       sibly contain upper ASCII characters whose possible combinations	 might
       be  a  UTF-8  special code.  The string is parsed and executed directly
       (using Tcl_EvalObjv) instead of compiling it and	 executing  the	 byte‐
       codes.	In  situations where it is known that the script will never be
       executed again, Tcl_Eval may be faster than Tcl_EvalObjEx.
	Tcl_Eval returns a completion code and result just like Tcl_EvalObjEx.
       Note: for backward compatibility with versions before Tcl 8.0, Tcl_Eval
       copies the value result in interp to interp->result (use is deprecated)
       where it can be accessed directly.
	This makes Tcl_Eval somewhat slower than Tcl_EvalEx, which does not do
       the copy.

       Tcl_EvalEx is an extended version of Tcl_Eval that takes additional ar‐
       guments	numBytes  and  flags.	For the efficiency reason given above,
       Tcl_EvalEx is generally preferred over Tcl_Eval.

       Tcl_GlobalEval and Tcl_GlobalEvalObj are older procedures that are  now
       deprecated.   They  are	similar to Tcl_EvalEx and Tcl_EvalObjEx except
       that the script is evaluated in the global namespace and	 its  variable
       context	consists  of  global variables only (it ignores any Tcl proce‐
       dures that are active).	These functions are equivalent	to  using  the
       TCL_EVAL_GLOBAL flag (see below).

       Tcl_VarEval  takes  any	number of string arguments of any length, con‐
       catenates them into a single string, then  calls	 Tcl_Eval  to  execute
       that string as a Tcl command.  It returns the result of the command and
       also modifies interp->result in the same way as Tcl_Eval.  The last ar‐
       gument to Tcl_VarEval must be (char *)NULL to indicate the end of argu‐
       ments.

       Tcl_VarEvalVA is the same as Tcl_VarEval except that instead of	taking
       a   variable   number   of   arguments	it  takes  an  argument	 list.
       Tcl_VarEvalVA is now deprecated.


FLAG BITS
       Any OR'ed combination of the following values may be used for the flags
       argument to procedures such as Tcl_EvalObjEx:

       TCL_EVAL_DIRECT	      This  flag  is only used by Tcl_EvalObjEx; it is
			      ignored by other procedures.  If this  flag  bit
			      is set, the script is not compiled to bytecodes;
			      instead it is executed directly as  is  done  by
			      Tcl_EvalEx.   The TCL_EVAL_DIRECT flag is useful
			      in situations where the contents of a value  are
			      going  to	 change	 immediately, so the bytecodes
			      will not be reused in a  future  execution.   In
			      this  case,  it  is faster to execute the script
			      directly.

       TCL_EVAL_GLOBAL	      If this flag is set, the script is evaluated  in
			      the  global  namespace  instead  of  the current
			      namespace and its variable context  consists  of
			      global variables only (it ignores any Tcl proce‐
			      dures that are active).


MISCELLANEOUS DETAILS
       During the processing of a Tcl command it is legal to make nested calls
       to  evaluate  other  commands  (this is how procedures and some control
       structures are implemented).  If a code other than TCL_OK  is  returned
       from a nested Tcl_EvalObjEx invocation, then the caller should normally
       return immediately, passing that same return code back to  its  caller,
       and  so on until the top-level application is reached.  A few commands,
       like for, will check for	 certain  return  codes,  like	TCL_BREAK  and
       TCL_CONTINUE, and process them specially without returning.

       Tcl_EvalObjEx  keeps track of how many nested Tcl_EvalObjEx invocations
       are in progress for interp.  If a code  of  TCL_RETURN,	TCL_BREAK,  or
       TCL_CONTINUE is about to be returned from the topmost Tcl_EvalObjEx in‐
       vocation for interp, it converts the return code to TCL_ERROR and  sets
       interp's	 result to an error message indicating that the return, break,
       or continue command was invoked in an inappropriate place.  This	 means
       that  top-level	applications  should  never  see  a  return  code from
       Tcl_EvalObjEx other than TCL_OK or TCL_ERROR.


KEYWORDS
       execute, file, global, result, script, value



Tcl				      8.1			   Tcl_Eval(3)

Tcl_CreateChannel(3)	    Tcl Library Procedures	  Tcl_CreateChannel(3)



______________________________________________________________________________

NAME
       Tcl_CreateChannel,    Tcl_GetChannelInstanceData,   Tcl_GetChannelType,
       Tcl_GetChannelName,	Tcl_GetChannelHandle,	   Tcl_GetChannelMode,
       Tcl_GetChannelBufferSize,  Tcl_SetChannelBufferSize, Tcl_NotifyChannel,
       Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_Channel‐
       BlockModeProc,  Tcl_ChannelCloseProc,  Tcl_ChannelClose2Proc, Tcl_Chan‐
       nelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc,  Tcl_Channel‐
       WideSeekProc,	 Tcl_ChannelTruncateProc,    Tcl_ChannelSetOptionProc,
       Tcl_ChannelGetOptionProc,    Tcl_ChannelWatchProc,     Tcl_ChannelGetH‐
       andleProc,   Tcl_ChannelFlushProc,   Tcl_ChannelHandlerProc,  Tcl_Chan‐
       nelThreadActionProc,   Tcl_IsChannelShared,    Tcl_IsChannelRegistered,
       Tcl_CutChannel,	      Tcl_SpliceChannel,	Tcl_IsChannelExisting,
       Tcl_ClearChannelHandlers, Tcl_GetChannelThread,	Tcl_ChannelBuffered  -
       procedures for creating and manipulating channels

SYNOPSIS
       #include <tcl.h>

       Tcl_Channel
       Tcl_CreateChannel(typePtr, channelName, instanceData, mask)

       ClientData
       Tcl_GetChannelInstanceData(channel)

       const Tcl_ChannelType *
       Tcl_GetChannelType(channel)

       const char *
       Tcl_GetChannelName(channel)

       int
       Tcl_GetChannelHandle(channel, direction, handlePtr)

       Tcl_ThreadId
       Tcl_GetChannelThread(channel)

       int
       Tcl_GetChannelMode(channel)

       int
       Tcl_GetChannelBufferSize(channel)

       Tcl_SetChannelBufferSize(channel, size)

       Tcl_NotifyChannel(channel, mask)

       int
       Tcl_BadChannelOption(interp, optionName, optionList)

       int
       Tcl_IsChannelShared(channel)

       int
       Tcl_IsChannelRegistered(interp, channel)

       int
       Tcl_IsChannelExisting(channelName)

       void
       Tcl_CutChannel(channel)

       void
       Tcl_SpliceChannel(channel)

       void
       Tcl_ClearChannelHandlers(channel)

       int
       Tcl_ChannelBuffered(channel)

       const char *
       Tcl_ChannelName(typePtr)

       Tcl_ChannelTypeVersion
       Tcl_ChannelVersion(typePtr)

       Tcl_DriverBlockModeProc *
       Tcl_ChannelBlockModeProc(typePtr)

       Tcl_DriverCloseProc *
       Tcl_ChannelCloseProc(typePtr)

       Tcl_DriverClose2Proc *
       Tcl_ChannelClose2Proc(typePtr)

       Tcl_DriverInputProc *
       Tcl_ChannelInputProc(typePtr)

       Tcl_DriverOutputProc *
       Tcl_ChannelOutputProc(typePtr)

       Tcl_DriverSeekProc *
       Tcl_ChannelSeekProc(typePtr)

       Tcl_DriverWideSeekProc *
       Tcl_ChannelWideSeekProc(typePtr)

       Tcl_DriverThreadActionProc *
       Tcl_ChannelThreadActionProc(typePtr)

       Tcl_DriverTruncateProc *
       Tcl_ChannelTruncateProc(typePtr)

       Tcl_DriverSetOptionProc *
       Tcl_ChannelSetOptionProc(typePtr)

       Tcl_DriverGetOptionProc *
       Tcl_ChannelGetOptionProc(typePtr)

       Tcl_DriverWatchProc *
       Tcl_ChannelWatchProc(typePtr)

       Tcl_DriverGetHandleProc *
       Tcl_ChannelGetHandleProc(typePtr)

       Tcl_DriverFlushProc *
       Tcl_ChannelFlushProc(typePtr)

       Tcl_DriverHandlerProc *
       Tcl_ChannelHandlerProc(typePtr)


ARGUMENTS
       const Tcl_ChannelType *typePtr (in)		Points	to a structure
							containing   the   ad‐
							dresses	 of procedures
							that can be called  to
							perform	 I/O and other
							functions on the chan‐
							nel.

       const char *channelName (in)			The name of this chan‐
							nel,  such  as	file3;
							must  not be in use by
							any other channel. Can
							be NULL, in which case
							the channel is created
							without a name. If the
							created channel is as‐
							signed	to  one of the
							standard      channels
							(stdin,	   stdout   or
							stderr), the  assigned
							channel	 name  will be
							the name of the	 stan‐
							dard channel.

       ClientData instanceData (in)			Arbitrary     one-word
							value to be associated
							with   this   channel.
							This value  is	passed
							to procedures in type‐
							Ptr when they are  in‐
							voked.

       int mask (in)					OR-ed  combination  of
							TCL_READABLE	   and
							TCL_WRITABLE  to indi‐
							cate whether a channel
							is     readable	   and
							writable.

       Tcl_Channel channel (in)				The channel to operate
							on.

       int direction (in)				TCL_READABLE means the
							input	 handle	    is
							wanted;	  TCL_WRITABLE
							means the output  han‐
							dle is wanted.

       ClientData *handlePtr (out)			Points to the location
							where the desired  OS-
							specific handle should
							be stored.

       int size (in)					The size, in bytes, of
							buffers to allocate in
							this channel.

       int mask (in)					An  OR-ed  combination
							of	 TCL_READABLE,
							TCL_WRITABLE	   and
							TCL_EXCEPTION that in‐
							dicates	 events	  that
							have  occurred on this
							channel.

       Tcl_Interp *interp (in)				Current	  interpreter.
							(can be NULL)

       const char *optionName (in)			Name  of  the  invalid
							option.

       const char *optionList (in)			Specific options  list
							(space	     separated
							words, without “-”) to
							append to the standard
							generic options	 list.
							Can    be   NULL   for
							generic options	 error
							message only.
______________________________________________________________________________

DESCRIPTION
       Tcl  uses a two-layered channel architecture. It provides a generic up‐
       per layer to enable C and Tcl programs to perform input and output  us‐
       ing  the	 same  APIs  for a variety of files, devices, sockets etc. The
       generic C APIs are described in the manual entry for  Tcl_OpenFileChan‐
       nel.

       The lower layer provides type-specific channel drivers for each type of
       device supported on each platform.  This manual entry describes	the  C
       APIs  used  to  communicate between the generic layer and the type-spe‐
       cific channel drivers.  It also explains how new types of channels  can
       be added by providing new channel drivers.

       Channel	drivers consist of a number of components: First, each channel
       driver provides a  Tcl_ChannelType  structure  containing  pointers  to
       functions implementing the various operations used by the generic layer
       to communicate with the channel driver. The  Tcl_ChannelType  structure
       and  the	 functions  referenced	by  it	are  described	in the section
       TCL_CHANNELTYPE, below.

       Second, channel drivers usually provide a Tcl  command  to  create  in‐
       stances of that type of channel. For example, the Tcl open command cre‐
       ates channels that use the file and command channel  drivers,  and  the
       Tcl  socket  command  creates channels that use TCP sockets for network
       communication.

       Third, a channel driver optionally provides a C function to open	 chan‐
       nel  instances  of  that type. For example, Tcl_OpenFileChannel opens a
       channel that uses the file channel driver, and Tcl_OpenTcpClient	 opens
       a channel that uses the TCP network protocol.  These creation functions
       typically use Tcl_CreateChannel internally to open the channel.

       To add a new type of channel you must implement a C API or a  Tcl  com‐
       mand  that  opens  a  channel by invoking Tcl_CreateChannel.  When your
       driver calls Tcl_CreateChannel it passes in a Tcl_ChannelType structure
       describing  the	driver's  I/O procedures.  The generic layer will then
       invoke the functions referenced in that structure to perform operations
       on the channel.

       Tcl_CreateChannel opens a new channel and associates the supplied type‐
       Ptr and instanceData with it. The channel is opened in the  mode	 indi‐
       cated  by  mask.	 For a discussion of channel drivers, their operations
       and the Tcl_ChannelType structure, see the section TCL_CHANNELTYPE, be‐
       low.

       Tcl_CreateChannel  interacts  with the code managing the standard chan‐
       nels. Once a standard channel was initialized either through a call  to
       Tcl_GetStdChannel  or a call to Tcl_SetStdChannel closing this standard
       channel will cause the next call to Tcl_CreateChannel to make  the  new
       channel	the  new  standard channel too. See Tcl_StandardChannels for a
       general treatise about standard channels and the behavior  of  the  Tcl
       library with regard to them.

       Tcl_GetChannelInstanceData  returns  the	 instance data associated with
       the channel in channel. This is the same as the	instanceData  argument
       in the call to Tcl_CreateChannel that created this channel.

       Tcl_GetChannelType  returns  a pointer to the Tcl_ChannelType structure
       used by the channel in the channel argument. This is the	 same  as  the
       typePtr	argument  in  the  call to Tcl_CreateChannel that created this
       channel.

       Tcl_GetChannelName returns a string containing the name associated with
       the  channel,  or NULL if the channelName argument to Tcl_CreateChannel
       was NULL.

       Tcl_GetChannelHandle places the OS-specific  device  handle  associated
       with  channel for the given direction in the location specified by han‐
       dlePtr and returns TCL_OK.  If the channel does not have a device  han‐
       dle  for	 the  specified direction, then TCL_ERROR is returned instead.
       Different channel drivers will return different types of handle.	 Refer
       to  the manual entries for each driver to determine what type of handle
       is returned.

       Tcl_GetChannelThread returns the id of the  thread  currently  managing
       the  specified  channel. This allows channel drivers to send their file
       events to the correct event queue even for a multi-threaded core.

       Tcl_GetChannelMode returns an OR-ed  combination	 of  TCL_READABLE  and
       TCL_WRITABLE, indicating whether the channel is open for input and out‐
       put.

       Tcl_GetChannelBufferSize returns the size, in bytes, of	buffers	 allo‐
       cated  to store input or output in channel. If the value was not set by
       a previous call to Tcl_SetChannelBufferSize, described below, then  the
       default value of 4096 is returned.

       Tcl_SetChannelBufferSize	 sets the size, in bytes, of buffers that will
       be allocated in subsequent operations on the channel to store input  or
       output. The size argument should be between one and one million, allow‐
       ing buffers of one byte to one million bytes. If size is	 outside  this
       range, Tcl_SetChannelBufferSize sets the buffer size to 4096.

       Tcl_NotifyChannel  is  called  by  a  channel driver to indicate to the
       generic layer that the events specified by mask have  occurred  on  the
       channel.	  Channel  drivers  are responsible for invoking this function
       whenever the channel handlers need to be called	for  the  channel  (or
       other  pending  tasks  like  a  write  flush should be performed).  See
       WATCHPROC below for more details.

       Tcl_BadChannelOption is called from driver  specific  setOptionProc  or
       getOptionProc to generate a complete error message.

       Tcl_ChannelBuffered  returns  the  number  of  bytes of input currently
       buffered in the internal buffer (push back area) of the channel itself.
       It  does not report about the data in the overall buffers for the stack
       of channels the supplied channel is part of.

       Tcl_IsChannelShared checks the refcount of the  specified  channel  and
       returns whether the channel was shared among multiple interpreters (re‐
       sult == 1) or not (result == 0).

       Tcl_IsChannelRegistered checks whether the specified channel is	regis‐
       tered in the given interpreter (result == 1) or not (result == 0).

       Tcl_IsChannelExisting  checks whether a channel with the specified name
       is registered in the (thread)-global list of all channels (result == 1)
       or not (result == 0).

       Tcl_CutChannel  removes	the  specified channel from the (thread)global
       list of all channels (of the current thread).  Application to a channel
       still registered in some interpreter is not allowed.  Also notifies the
       driver if the  Tcl_ChannelType  version	is  TCL_CHANNEL_VERSION_4  (or
       higher), and Tcl_DriverThreadActionProc is defined for it.

       Tcl_SpliceChannel adds the specified channel to the (thread)global list
       of all channels (of the current thread).	 Application to a channel reg‐
       istered	in  some interpreter is not allowed.  Also notifies the driver
       if the Tcl_ChannelType version is  TCL_CHANNEL_VERSION_4	 (or  higher),
       and Tcl_DriverThreadActionProc is defined for it.

       Tcl_ClearChannelHandlers removes all channel handlers and event scripts
       associated with the specified channel, thus  shutting  down  all	 event
       processing for this channel.

TCL_CHANNELTYPE
       A  channel  driver  provides  a Tcl_ChannelType structure that contains
       pointers to functions that implement the various operations on a	 chan‐
       nel;  these operations are invoked as needed by the generic layer.  The
       structure was versioned starting in Tcl 8.3.2/8.4 to correct a  problem
       with  stacked channel drivers.  See the OLD CHANNEL TYPES section below
       for details about the old structure.

       The Tcl_ChannelType structure contains the following fields:

	      typedef struct Tcl_ChannelType {
		      const char *typeName;
		      Tcl_ChannelTypeVersion version;
		      Tcl_DriverCloseProc *closeProc;
		      Tcl_DriverInputProc *inputProc;
		      Tcl_DriverOutputProc *outputProc;
		      Tcl_DriverSeekProc *seekProc;
		      Tcl_DriverSetOptionProc *setOptionProc;
		      Tcl_DriverGetOptionProc *getOptionProc;
		      Tcl_DriverWatchProc *watchProc;
		      Tcl_DriverGetHandleProc *getHandleProc;
		      Tcl_DriverClose2Proc *close2Proc;
		      Tcl_DriverBlockModeProc *blockModeProc;
		      Tcl_DriverFlushProc *flushProc;
		      Tcl_DriverHandlerProc *handlerProc;
		      Tcl_DriverWideSeekProc *wideSeekProc;
		      Tcl_DriverThreadActionProc *threadActionProc;
		      Tcl_DriverTruncateProc *truncateProc;
	      } Tcl_ChannelType;

       It is not necessary to provide implementations for all  channel	opera‐
       tions.  Those which are not necessary may be set to NULL in the struct:
       blockModeProc, seekProc, setOptionProc,	getOptionProc,	getHandleProc,
       and  close2Proc,	 in  addition to flushProc, handlerProc, threadAction‐
       Proc, and truncateProc.	Other functions that cannot be implemented  in
       a meaningful way should return EINVAL when called, to indicate that the
       operations  they	 represent  are	 not   available.   Also   note	  that
       wideSeekProc can be NULL if seekProc is.

       The  user  should  only use the above structure for Tcl_ChannelType in‐
       stantiation.  When referencing fields in a  Tcl_ChannelType  structure,
       the  following functions should be used to obtain the values: Tcl_Chan‐
       nelName,	 Tcl_ChannelVersion,  Tcl_ChannelBlockModeProc,	  Tcl_Channel‐
       CloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOut‐
       putProc,	  Tcl_ChannelSeekProc,	 Tcl_ChannelWideSeekProc,    Tcl_Chan‐
       nelThreadActionProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc,
       Tcl_ChannelGetOptionProc,    Tcl_ChannelWatchProc,     Tcl_ChannelGetH‐
       andleProc, Tcl_ChannelFlushProc, or Tcl_ChannelHandlerProc.

       The change to the structures was made in such a way that standard chan‐
       nel types are binary  compatible.   However,  channel  types  that  use
       stacked channels (i.e. TLS, Trf) have new versions to correspond to the
       above change since the previous code for stacked channels had problems.

   TYPENAME
       The typeName field contains a null-terminated  string  that  identifies
       the  type  of  the  device  implemented	by  this driver, e.g.  file or
       socket.

       This value can be  retrieved  with  Tcl_ChannelName,  which  returns  a
       pointer to the string.

   VERSION
       The  version  field  should be set to the version of the structure that
       you  require.  TCL_CHANNEL_VERSION_2  is	  the	minimum	  recommended.
       TCL_CHANNEL_VERSION_3  must  be set to specify the wideSeekProc member.
       TCL_CHANNEL_VERSION_4 must be set to specify the threadActionProc  mem‐
       ber  (includes  wideSeekProc).	TCL_CHANNEL_VERSION_5  must  be set to
       specify the truncateProc members (includes wideSeekProc	and  threadAc‐
       tionProc).  If it is not set to any of these, then this Tcl_ChannelType
       is assumed to have the original structure.  See OLD CHANNEL  TYPES  for
       more details.  While Tcl will recognize and function with either struc‐
       tures, stacked channels must be of at  least  TCL_CHANNEL_VERSION_2  to
       function correctly.

       This  value can be retrieved with Tcl_ChannelVersion, which returns one
       of TCL_CHANNEL_VERSION_5, TCL_CHANNEL_VERSION_4, TCL_CHANNEL_VERSION_3,
       TCL_CHANNEL_VERSION_2 or TCL_CHANNEL_VERSION_1.

   BLOCKMODEPROC
       The  blockModeProc  field  contains the address of a function called by
       the generic layer to set blocking and nonblocking mode on  the  device.
       BlockModeProc should match the following prototype:

	      typedef int Tcl_DriverBlockModeProc(
		      ClientData instanceData,
		      int mode);

       The  instanceData  is the same as the value passed to Tcl_CreateChannel
       when  this  channel  was	 created.   The	 mode	argument   is	either
       TCL_MODE_BLOCKING or TCL_MODE_NONBLOCKING to set the device into block‐
       ing or nonblocking mode. The function should return zero if the	opera‐
       tion  was  successful,  or  a nonzero POSIX error code if the operation
       failed.

       If the operation is successful, the function can	 modify	 the  supplied
       instanceData to record that the channel entered blocking or nonblocking
       mode and to implement the blocking or nonblocking behavior.   For  some
       device  types, the blocking and nonblocking behavior can be implemented
       by the underlying operating system; for other device types, the	behav‐
       ior must be emulated in the channel driver.

       This  value  can	 be retrieved with Tcl_ChannelBlockModeProc, which re‐
       turns a pointer to the function.

       A channel driver not supplying a blockModeProc has  to  be  very,  very
       careful.	 It  has to tell the generic layer exactly which blocking mode
       is acceptable to it, and should this also document for the user so that
       the  blocking  mode  of	the  channel is not changed to an unacceptable
       value. Any confusion here may lead the interpreter into a (spurious and
       difficult to find) deadlock.

   CLOSEPROC AND CLOSE2PROC
       The  closeProc  field  contains the address of a function called by the
       generic layer to clean up driver-related information when  the  channel
       is closed. CloseProc must match the following prototype:

	      typedef int Tcl_DriverCloseProc(
		      ClientData instanceData,
		      Tcl_Interp *interp);

       The instanceData argument is the same as the value provided to Tcl_Cre‐
       ateChannel when the channel was created. The  function  should  release
       any  storage  maintained	 by  the  channel driver for this channel, and
       close the input and output devices encapsulated by  this	 channel.  All
       queued output will have been flushed to the device before this function
       is called, and no further driver operations will be invoked on this in‐
       stance  after calling the closeProc. If the close operation is success‐
       ful, the procedure should return zero; otherwise	 it  should  return  a
       nonzero POSIX error code. In addition, if an error occurs and interp is
       not NULL, the procedure should store an error  message  in  the	inter‐
       preter's result.

       Alternatively,  channels	 that support closing the read and write sides
       independently may set closeProc to TCL_CLOSE2PROC and set close2Proc to
       the address of a function that matches the following prototype:

	      typedef int Tcl_DriverClose2Proc(
		      ClientData instanceData,
		      Tcl_Interp *interp,
		      int flags);

       The close2Proc will be called with flags set to an OR'ed combination of
       TCL_CLOSE_READ or TCL_CLOSE_WRITE to indicate that  the	driver	should
       close  the  read	 and/or write side of the channel.  The channel driver
       may be invoked to perform additional operations on  the	channel	 after
       close2Proc  is  called  to  close one or both sides of the channel.  If
       flags is 0 (zero), the driver should close the channel  in  the	manner
       described  above	 for closeProc.	 No further operations will be invoked
       on this instance after close2Proc is called with all flags cleared.  In
       all  cases, the close2Proc function should return zero if the close op‐
       eration was successful; otherwise it should return a nonzero POSIX  er‐
       ror  code.  In addition, if an error occurs and interp is not NULL, the
       procedure should store an error message in the interpreter's result.

       The closeProc and close2Proc values can be retrieved with  Tcl_Channel‐
       CloseProc  or  Tcl_ChannelClose2Proc, which return a pointer to the re‐
       spective function.

   INPUTPROC
       The inputProc field contains the address of a function  called  by  the
       generic	layer  to read data from the file or device and store it in an
       internal buffer. InputProc must match the following prototype:

	      typedef int Tcl_DriverInputProc(
		      ClientData instanceData,
		      char *buf,
		      int bufSize,
		      int *errorCodePtr);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       the  channel was created.  The buf argument points to an array of bytes
       in which to store input from the device, and the bufSize argument indi‐
       cates how many bytes are available at buf.

       The errorCodePtr argument points to an integer variable provided by the
       generic layer. If an error occurs, the function should set the variable
       to a POSIX error code that identifies the error that occurred.

       The function should read data from the input device encapsulated by the
       channel and store it at buf.  On success, the function should return  a
       nonnegative  integer indicating how many bytes were read from the input
       device and stored at buf. On error, the function should return  -1.  If
       an  error  occurs  after	 some data has been read from the device, that
       data is lost.

       If inputProc can determine that the input device has some  data	avail‐
       able  but  less	than  requested	 by the bufSize argument, the function
       should only attempt to read as much data as  is	available  and	return
       without	blocking. If the input device has no data available whatsoever
       and the channel is in nonblocking mode, the function should  return  an
       EAGAIN  error. If the input device has no data available whatsoever and
       the channel is in blocking mode, the  function  should  block  for  the
       shortest possible time until at least one byte of data can be read from
       the device; then, it should return as much data as it can read  without
       blocking.

       This  value can be retrieved with Tcl_ChannelInputProc, which returns a
       pointer to the function.

   OUTPUTPROC
       The outputProc field contains the address of a function called  by  the
       generic	layer  to  transfer data from an internal buffer to the output
       device.	OutputProc must match the following prototype:

	      typedef int Tcl_DriverOutputProc(
		      ClientData instanceData,
		      const char *buf,
		      int toWrite,
		      int *errorCodePtr);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       the channel was created. The buf argument contains an array of bytes to
       be written to the device, and the toWrite argument indicates  how  many
       bytes are to be written from the buf argument.

       The errorCodePtr argument points to an integer variable provided by the
       generic layer. If an error occurs, the function should set  this	 vari‐
       able to a POSIX error code that identifies the error.

       The function should write the data at buf to the output device encapsu‐
       lated by the channel. On success, the function should return a nonnega‐
       tive  integer  indicating how many bytes were written to the output de‐
       vice.  The return value is normally the same as	toWrite,  but  may  be
       less  in some cases such as if the output operation is interrupted by a
       signal. If an error occurs the function should return -1.  In  case  of
       error, some data may have been written to the device.

       If the channel is nonblocking and the output device is unable to absorb
       any data whatsoever, the function should return -1 with an EAGAIN error
       without writing any data.

       This value can be retrieved with Tcl_ChannelOutputProc, which returns a
       pointer to the function.

   SEEKPROC AND WIDESEEKPROC
       The seekProc field contains the address of a  function  called  by  the
       generic	layer  to  move	 the access point at which subsequent input or
       output operations will be applied. SeekProc must	 match	the  following
       prototype:

	      typedef int Tcl_DriverSeekProc(
		      ClientData instanceData,
		      long offset,
		      int seekMode,
		      int *errorCodePtr);

       The instanceData argument is the same as the value given to Tcl_Create‐
       Channel when this channel was created.  Offset and  seekMode  have  the
       same meaning as for the Tcl_Seek procedure (described in the manual en‐
       try for Tcl_OpenFileChannel).

       The errorCodePtr argument points to an integer variable provided by the
       generic	layer for returning errno values from the function.  The func‐
       tion should set this variable to a POSIX error code if an error occurs.
       The function should store an EINVAL error code if the channel type does
       not implement seeking.

       The return value is the new access point or -1 in case of error. If  an
       error occurred, the function should not move the access point.

       If  there is a non-NULL seekProc field, the wideSeekProc field may con‐
       tain the address of an alternative function to use which	 handles  wide
       (i.e.  larger  than  32-bit)  offsets,  so  allowing seeks within files
       larger than 2GB.	 The wideSeekProc will be called in preference to  the
       seekProc,  but  both  must  be  defined if the wideSeekProc is defined.
       WideSeekProc must match the following prototype:

	      typedef Tcl_WideInt Tcl_DriverWideSeekProc(
		      ClientData instanceData,
		      Tcl_WideInt offset,
		      int seekMode,
		      int *errorCodePtr);

       The arguments and return values mean the same thing  as	with  seekProc
       above,  except that the type of offsets and the return type are differ‐
       ent.

       The seekProc value can be retrieved with Tcl_ChannelSeekProc, which re‐
       turns  a pointer to the function, and similarly the wideSeekProc can be
       retrieved with Tcl_ChannelWideSeekProc.

   SETOPTIONPROC
       The setOptionProc field contains the address of a  function  called  by
       the  generic  layer to set a channel type specific option on a channel.
       setOptionProc must match the following prototype:

	      typedef int Tcl_DriverSetOptionProc(
		      ClientData instanceData,
		      Tcl_Interp *interp,
		      const char *optionName,
		      const char *newValue);

       optionName is the name of an option to set, and	newValue  is  the  new
       value for that option, as a string. The instanceData is the same as the
       value given to Tcl_CreateChannel when this  channel  was	 created.  The
       function should do whatever channel type specific action is required to
       implement the new value of the option.

       Some options are handled by the generic code and this function is never
       called to set them, e.g. -blockmode. Other options are specific to each
       channel type and the setOptionProc procedure of the channel driver will
       get  called  to	implement  them.  The setOptionProc field can be NULL,
       which indicates that this channel type supports no  type	 specific  op‐
       tions.

       If  the	option	value  is  successfully modified to the new value, the
       function returns TCL_OK.	 It should call Tcl_BadChannelOption which it‐
       self  returns TCL_ERROR if the optionName is unrecognized.  If newValue
       specifies a value for the option that is not supported or if  a	system
       call  error  occurs,  the function should leave an error message in the
       result of interp if interp is not NULL. The function should  also  call
       Tcl_SetErrno to store an appropriate POSIX error code.

       This  value  can	 be retrieved with Tcl_ChannelSetOptionProc, which re‐
       turns a pointer to the function.

   GETOPTIONPROC
       The getOptionProc field contains the address of a  function  called  by
       the generic layer to get the value of a channel type specific option on
       a channel. getOptionProc must match the following prototype:

	      typedef int Tcl_DriverGetOptionProc(
		      ClientData instanceData,
		      Tcl_Interp *interp,
		      const char *optionName,
		      Tcl_DString *optionValue);

       OptionName is the name of an option supported by this type of  channel.
       If  the option name is not NULL, the function stores its current value,
       as a string, in the Tcl dynamic string optionValue.  If	optionName  is
       NULL,  the  function  stores  in optionValue an alternating list of all
       supported options and their current values.  On success,	 the  function
       returns	TCL_OK.	  It should call Tcl_BadChannelOption which itself re‐
       turns TCL_ERROR if the optionName is unrecognized. If a system call er‐
       ror occurs, the function should leave an error message in the result of
       interp if interp is not NULL. The function should also call  Tcl_SetEr‐
       rno to store an appropriate POSIX error code.

       Some options are handled by the generic code and this function is never
       called to retrieve their value, e.g. -blockmode. Other options are spe‐
       cific to each channel type and the getOptionProc procedure of the chan‐
       nel driver will get called to implement them. The  getOptionProc	 field
       can  be	NULL,  which indicates that this channel type supports no type
       specific options.

       This value can be retrieved with	 Tcl_ChannelGetOptionProc,  which  re‐
       turns a pointer to the function.

   WATCHPROC
       The  watchProc  field  contains the address of a function called by the
       generic layer to initialize the event notification mechanism to	notice
       events of interest on this channel.  WatchProc should match the follow‐
       ing prototype:

	      typedef void Tcl_DriverWatchProc(
		      ClientData instanceData,
		      int mask);

       The instanceData is the same as the value passed	 to  Tcl_CreateChannel
       when  this  channel was created. The mask argument is an OR-ed combina‐
       tion of TCL_READABLE,  TCL_WRITABLE  and	 TCL_EXCEPTION;	 it  indicates
       events the caller is interested in noticing on this channel.

       The  function  should initialize device type specific mechanisms to no‐
       tice when an event of interest is present on the channel.  When one  or
       more of the designated events occurs on the channel, the channel driver
       is responsible for calling  Tcl_NotifyChannel  to  inform  the  generic
       channel	module.	 The driver should take care not to starve other chan‐
       nel drivers or sources of callbacks by invoking	Tcl_NotifyChannel  too
       frequently.   Fairness  can  be insured by using the Tcl event queue to
       allow the channel event to be scheduled in sequence with other  events.
       See  the	 description  of Tcl_QueueEvent for details on how to queue an
       event.

       This value can be retrieved with Tcl_ChannelWatchProc, which returns  a
       pointer to the function.

   GETHANDLEPROC
       The  getHandleProc  field  contains the address of a function called by
       the generic layer to retrieve a device-specific handle from  the	 chan‐
       nel.  GetHandleProc should match the following prototype:

	      typedef int Tcl_DriverGetHandleProc(
		      ClientData instanceData,
		      int direction,
		      ClientData *handlePtr);

       InstanceData  is the same as the value passed to Tcl_CreateChannel when
       this channel was created. The direction argument is either TCL_READABLE
       to  retrieve the handle used for input, or TCL_WRITABLE to retrieve the
       handle used for output.

       If the channel implementation has device-specific handles, the function
       should retrieve the appropriate handle associated with the channel, ac‐
       cording the direction argument.	The handle should be stored in the lo‐
       cation referred to by handlePtr, and TCL_OK should be returned.	If the
       channel is not open for the specified direction, or if the channel  im‐
       plementation  does  not	use device handles, the function should return
       TCL_ERROR.

       This value can be retrieved with	 Tcl_ChannelGetHandleProc,  which  re‐
       turns a pointer to the function.

   FLUSHPROC
       The flushProc field is currently reserved for future use.  It should be
       set to NULL.  FlushProc should match the following prototype:

	      typedef int Tcl_DriverFlushProc(
		      ClientData instanceData);

       This value can be retrieved with Tcl_ChannelFlushProc, which returns  a
       pointer to the function.

   HANDLERPROC
       The  handlerProc field contains the address of a function called by the
       generic layer to notify the channel that an event occurred.  It	should
       be  defined  for	 stacked  channel  drivers that wish to be notified of
       events that occur on the	 underlying  (stacked)	channel.   HandlerProc
       should match the following prototype:

	      typedef int Tcl_DriverHandlerProc(
		      ClientData instanceData,
		      int interestMask);

       InstanceData  is the same as the value passed to Tcl_CreateChannel when
       this channel was created.  The interestMask is an OR-ed combination  of
       TCL_READABLE  or TCL_WRITABLE; it indicates what type of event occurred
       on this channel.

       This value can be retrieved with Tcl_ChannelHandlerProc, which  returns
       a pointer to the function.


   THREADACTIONPROC
       The  threadActionProc field contains the address of the function called
       by the generic layer when a channel is created,	closed,	 or  going  to
       move  to a different thread, i.e. whenever thread-specific driver state
       might have to initialized or updated.  It  can  be  NULL.   The	action
       TCL_CHANNEL_THREAD_REMOVE  is  used to notify the driver that it should
       update or remove any thread-specific data it might be  maintaining  for
       the channel.

       The  action TCL_CHANNEL_THREAD_INSERT is used to notify the driver that
       it should update or initialize any thread-specific  data	 it  might  be
       maintaining using the calling thread as the associate. See Tcl_CutChan‐
       nel and Tcl_SpliceChannel for more detail.

	      typedef void Tcl_DriverThreadActionProc(
		      ClientData instanceData,
		      int action);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       this channel was created.

       These  values  can be retrieved with Tcl_ChannelThreadActionProc, which
       returns a pointer to the function.

   TRUNCATEPROC
       The truncateProc field contains the address of the function  called  by
       the generic layer when a channel is truncated to some length. It can be
       NULL.

	      typedef int Tcl_DriverTruncateProc(
		      ClientData instanceData,
		      Tcl_WideInt length);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       this  channel was created, and length is the new length of the underly‐
       ing file, which should not be negative. The result should be 0 on  suc‐
       cess or an errno code (suitable for use with Tcl_SetErrno) on failure.

       These  values  can be retrieved with Tcl_ChannelTruncateProc, which re‐
       turns a pointer to the function.

TCL_BADCHANNELOPTION
       This procedure generates a “bad option” error message in an  (optional)
       interpreter.  It is used by channel drivers when an invalid Set/Get op‐
       tion is requested. Its purpose is to concatenate	 the  generic  options
       list  to the specific ones and factorize the generic options error mes‐
       sage string.

       It always returns TCL_ERROR

       An error message is generated in interp's result value to indicate that
       a command was invoked with a bad option.	 The message has the form
		  bad option "blah": should be one of
		  <...generic options...>+<...specific options...>
       so you get for instance:
		  bad option "-blah": should be one of -blocking,
		  -buffering, -buffersize, -eofchar, -translation,
		  -peername, or -sockname
       when called with optionList equal to “peername sockname”

       “blah”  is  the optionName argument and “<specific options>” is a space
       separated list of specific option words.	 The function takes good  care
       of  inserting minus signs before each option, commas after, and an “or”
       before the last option.

OLD CHANNEL TYPES
       The original (8.3.1 and below) Tcl_ChannelType structure	 contains  the
       following fields:

	      typedef struct Tcl_ChannelType {
		  const char *typeName;
		  Tcl_DriverBlockModeProc *blockModeProc;
		  Tcl_DriverCloseProc *closeProc;
		  Tcl_DriverInputProc *inputProc;
		  Tcl_DriverOutputProc *outputProc;
		  Tcl_DriverSeekProc *seekProc;
		  Tcl_DriverSetOptionProc *setOptionProc;
		  Tcl_DriverGetOptionProc *getOptionProc;
		  Tcl_DriverWatchProc *watchProc;
		  Tcl_DriverGetHandleProc *getHandleProc;
		  Tcl_DriverClose2Proc *close2Proc;
	      } Tcl_ChannelType;

       It  is  still possible to create channel with the above structure.  The
       internal channel code will determine the version.  It is imperative  to
       use  the	 new  Tcl_ChannelType  structure if you are creating a stacked
       channel driver, due to problems with the earlier stacked channel imple‐
       mentation (in 8.2.0 to 8.3.1).

       Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part of
       the 8.4 development cycle) the Tcl_ChannelType structure contained  the
       following fields:

	      typedef struct Tcl_ChannelType {
		  const char *typeName;
		  Tcl_ChannelTypeVersion version;
		  Tcl_DriverCloseProc *closeProc;
		  Tcl_DriverInputProc *inputProc;
		  Tcl_DriverOutputProc *outputProc;
		  Tcl_DriverSeekProc *seekProc;
		  Tcl_DriverSetOptionProc *setOptionProc;
		  Tcl_DriverGetOptionProc *getOptionProc;
		  Tcl_DriverWatchProc *watchProc;
		  Tcl_DriverGetHandleProc *getHandleProc;
		  Tcl_DriverClose2Proc *close2Proc;
		  Tcl_DriverBlockModeProc *blockModeProc;
		  Tcl_DriverFlushProc *flushProc;
		  Tcl_DriverHandlerProc *handlerProc;
		  Tcl_DriverTruncateProc *truncateProc;
	      } Tcl_ChannelType;

       When  the  above structure is registered as a channel type, the version
       field should always be TCL_CHANNEL_VERSION_2.

SEE ALSO
       Tcl_Close(3),	     Tcl_OpenFileChannel(3),	      Tcl_SetErrno(3),
       Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)

KEYWORDS
       blocking, channel driver, channel registration, channel type, nonblock‐
       ing



Tcl				      8.4		  Tcl_CreateChannel(3)

Tcl_CreateFileHandler(3)    Tcl Library Procedures    Tcl_CreateFileHandler(3)



______________________________________________________________________________

NAME
       Tcl_CreateFileHandler,	Tcl_DeleteFileHandler  -  associate  procedure
       callbacks with files or devices (Unix only)

SYNOPSIS
       #include <tcl.h>

       Tcl_CreateFileHandler(fd, mask, proc, clientData)

       Tcl_DeleteFileHandler(fd)

ARGUMENTS
       int fd (in)			     Unix file descriptor for an  open
					     file or device.

       int mask (in)			     Conditions	  under	  which	  proc
					     should be called: OR-ed  combina‐
					     tion	of	 TCL_READABLE,
					     TCL_WRITABLE, and	TCL_EXCEPTION.
					     May  be  set  to 0 to temporarily
					     disable a handler.

       Tcl_FileProc *proc (in)		     Procedure to invoke whenever  the
					     file  or device indicated by file
					     meets the conditions specified by
					     mask.

       ClientData clientData (in)	     Arbitrary	one-word value to pass
					     to proc.
______________________________________________________________________________

DESCRIPTION
       Tcl_CreateFileHandler arranges for proc to be  invoked  in  the	future
       whenever I/O becomes possible on a file or an exceptional condition ex‐
       ists for the file.  The file is indicated by fd, and the conditions  of
       interest	 are indicated by mask.	 For example, if mask is TCL_READABLE,
       proc will be called when the file is readable.  The callback to proc is
       made by Tcl_DoOneEvent, so Tcl_CreateFileHandler is only useful in pro‐
       grams that dispatch events through Tcl_DoOneEvent or through  Tcl  com‐
       mands such as vwait.

       Proc should have arguments and result that match the type Tcl_FileProc:

	      typedef void Tcl_FileProc(
		      ClientData clientData,
		      int mask);

       The  clientData	parameter to proc is a copy of the clientData argument
       given to Tcl_CreateFileHandler when the callback	 was  created.	 Typi‐
       cally,  clientData  points  to a data structure containing application-
       specific information about the file.  Mask is an integer mask  indicat‐
       ing which of the requested conditions actually exists for the file;  it
       will contain a subset of the bits in the mask argument  to  Tcl_Create‐
       FileHandler.

       There  may exist only one handler for a given file at a given time.  If
       Tcl_CreateFileHandler is called when a handler already exists  for  fd,
       then  the  new  callback	 replaces  the information that was previously
       recorded.

       Tcl_DeleteFileHandler may be called to delete the file handler for  fd;
       if no handler exists for the file given by fd then the procedure has no
       effect.

       The purpose of file handlers is to enable an application to respond  to
       events  while  waiting  for files to become ready for I/O.  For this to
       work correctly, the application may need to use non-blocking I/O opera‐
       tions  on the files for which handlers are declared.  Otherwise the ap‐
       plication may block if it reads or writes too much data; while  waiting
       for  the	 I/O  to  complete the application will not be able to service
       other events. Use Tcl_SetChannelOption with -blocking to set the	 chan‐
       nel into blocking or nonblocking mode as required.

       Note  that  these interfaces are only supported by the Unix implementa‐
       tion of the Tcl notifier.

SEE ALSO
       fileevent(n), Tcl_CreateTimerHandler(3), Tcl_DoWhenIdle(3)

KEYWORDS
       callback, file, handler



Tcl				      8.0	      Tcl_CreateFileHandler(3)

Tcl_SetChannelError(3)	    Tcl Library Procedures	Tcl_SetChannelError(3)



______________________________________________________________________________

NAME
       Tcl_SetChannelError,   Tcl_SetChannelErrorInterp,  Tcl_GetChannelError,
       Tcl_GetChannelErrorInterp - functions to create/intercept Tcl errors by
       channel drivers.

SYNOPSIS
       #include <tcl.h>

       void
       Tcl_SetChannelError(chan, msg)

       void
       Tcl_SetChannelErrorInterp(interp, msg)

       void
       Tcl_GetChannelError(chan, msgPtr)

       void
       Tcl_GetChannelErrorInterp(interp, msgPtr)


ARGUMENTS
       Tcl_Channel chan (in)	      Refers  to  the Tcl channel whose bypass
				      area is accessed.

       Tcl_Interp* interp (in)	      Refers to the Tcl interpreter whose  by‐
				      pass area is accessed.

       Tcl_Obj* msg (in)	      Error  message put into a bypass area. A
				      list of return options and values,  fol‐
				      lowed  by a string message. Both message
				      and the option/value information are op‐
				      tional.

       Tcl_Obj** msgPtr (out)	      Reference	 to  a place where the message
				      stored in the accessed bypass  area  can
				      be stored in.
______________________________________________________________________________

DESCRIPTION
       The  current definition of a Tcl channel driver does not permit the di‐
       rect return of arbitrary error messages, except for the setting and re‐
       trieval of channel options. All other functions are restricted to POSIX
       error codes.

       The functions described here overcome this limitation. Channel  drivers
       are allowed to use Tcl_SetChannelError and Tcl_SetChannelErrorInterp to
       place arbitrary error messages in bypass areas defined for channels and
       interpreters.  And  the	generic I/O layer uses Tcl_GetChannelError and
       Tcl_GetChannelErrorInterp to look for messages in the bypass areas  and
       arrange	for  their  return  as	errors. The POSIX error codes set by a
       driver are used now if and only if no messages are present.

       Tcl_SetChannelError stores error information in the bypass area of  the
       specified channel. The number of references to the msg value goes up by
       one. Previously stored information will be discarded, by releasing  the
       reference held by the channel. The channel reference must not be NULL.

       Tcl_SetChannelErrorInterp  stores  error information in the bypass area
       of the specified interpreter. The number of references to the msg value
       goes up by one. Previously stored information will be discarded, by re‐
       leasing the reference held by the interpreter. The  interpreter	refer‐
       ence must not be NULL.

       Tcl_GetChannelError  places either the error message held in the bypass
       area of the specified channel into msgPtr, or NULL; and resets the  by‐
       pass,  that  is, after an invocation all following invocations will re‐
       turn NULL, until an intervening invocation of Tcl_SetChannelError  with
       a non-NULL message. The msgPtr must not be NULL. The reference count of
       the message is not touched.  The reference previously held by the chan‐
       nel  is	now held by the caller of the function and it is its responsi‐
       bility to release that reference when it is done with the value.

       Tcl_GetChannelErrorInterp places either the error message held  in  the
       bypass  area of the specified interpreter into msgPtr, or NULL; and re‐
       sets the bypass, that is, after an invocation all following invocations
       will  return NULL, until an intervening invocation of Tcl_SetChannelEr‐
       rorInterp with a non-NULL message. The msgPtr must  not	be  NULL.  The
       reference  count	 of  the message is not touched.  The reference previ‐
       ously held by the interpreter is now held by the caller of the function
       and  it is its responsibility to release that reference when it is done
       with the value.

       Which functions of a channel driver are allowed	to  use	 which	bypass
       function	 is  listed below, as is which functions of the public channel
       API may leave a messages in the bypass areas.

       Tcl_DriverCloseProc
	      May use Tcl_SetChannelErrorInterp, and only this function.

       Tcl_DriverInputProc
	      May use Tcl_SetChannelError, and only this function.

       Tcl_DriverOutputProc
	      May use Tcl_SetChannelError, and only this function.

       Tcl_DriverSeekProc
	      May use Tcl_SetChannelError, and only this function.

       Tcl_DriverWideSeekProc
	      May use Tcl_SetChannelError, and only this function.

       Tcl_DriverSetOptionProc
	      Has already the ability to pass arbitrary error  messages.  Must
	      not use any of the new functions.

       Tcl_DriverGetOptionProc
	      Has  already  the ability to pass arbitrary error messages. Must
	      not use any of the new functions.

       Tcl_DriverWatchProc
	      Must not use any of the new functions. Is internally called  and
	      has no ability to return any type of error whatsoever.

       Tcl_DriverBlockModeProc
	      May use Tcl_SetChannelError, and only this function.

       Tcl_DriverGetHandleProc
	      Must  not	 use  any of the new functions. It is only a low-level
	      function, and not used by Tcl commands.

       Tcl_DriverHandlerProc
	      Must not use any of the new functions. Is internally called  and
	      has no ability to return any type of error whatsoever.

       Given the information above the following public functions of the Tcl C
       API are affected by these changes; when these functions are called, the
       channel may now contain a stored arbitrary error message requiring pro‐
       cessing by the caller.

	      Tcl_Flush		 Tcl_GetsObj	      Tcl_Gets
	      Tcl_ReadChars	 Tcl_ReadRaw	      Tcl_Read
	      Tcl_Seek		 Tcl_StackChannel     Tcl_Tell
	      Tcl_WriteChars	 Tcl_WriteObj	      Tcl_WriteRaw
	      Tcl_Write


       All other API functions are unchanged. In particular, the functions be‐
       low leave all their error information in the interpreter result.

	      Tcl_Close		 Tcl_UnstackChannel   Tcl_UnregisterChannel


SEE ALSO
       Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)

KEYWORDS
       channel driver, error messages, channel type



Tcl				      8.5		Tcl_SetChannelError(3)

Tcl_UniCharIsAlpha(3)	    Tcl Library Procedures	 Tcl_UniCharIsAlpha(3)



______________________________________________________________________________

NAME
       Tcl_UniCharIsAlnum,	Tcl_UniCharIsAlpha,	 Tcl_UniCharIsControl,
       Tcl_UniCharIsDigit,	 Tcl_UniCharIsGraph,	   Tcl_UniCharIsLower,
       Tcl_UniCharIsPrint,	 Tcl_UniCharIsPunct,	   Tcl_UniCharIsSpace,
       Tcl_UniCharIsUpper, Tcl_UniCharIsWordChar - routines for classification
       of Tcl_UniChar characters

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_UniCharIsAlnum(ch)

       int
       Tcl_UniCharIsAlpha(ch)

       int
       Tcl_UniCharIsControl(ch)

       int
       Tcl_UniCharIsDigit(ch)

       int
       Tcl_UniCharIsGraph(ch)

       int
       Tcl_UniCharIsLower(ch)

       int
       Tcl_UniCharIsPrint(ch)

       int
       Tcl_UniCharIsPunct(ch)

       int
       Tcl_UniCharIsSpace(ch)

       int
       Tcl_UniCharIsUpper(ch)

       int
       Tcl_UniCharIsWordChar(ch)

ARGUMENTS
       int ch (in)	    The Tcl_UniChar to be examined.
______________________________________________________________________________


DESCRIPTION
       All  of	the routines described examine Unicode characters and return a
       boolean value. A non-zero return value means that  the  character  does
       belong  to  the character class associated with the called routine. The
       rest of this document just describes the character  classes  associated
       with the various routines.


CHARACTER CLASSES
       Tcl_UniCharIsAlnum  tests  if  the character is an alphanumeric Unicode
       character.

       Tcl_UniCharIsAlpha tests if the	character  is  an  alphabetic  Unicode
       character.

       Tcl_UniCharIsControl  tests if the character is a Unicode control char‐
       acter.

       Tcl_UniCharIsDigit tests if the character is a numeric Unicode  charac‐
       ter.

       Tcl_UniCharIsGraph  tests if the character is any Unicode print charac‐
       ter except space.

       Tcl_UniCharIsLower tests if the character is a lowercase Unicode	 char‐
       acter.

       Tcl_UniCharIsPrint tests if the character is a Unicode print character.

       Tcl_UniCharIsPunct  tests  if  the  character  is a Unicode punctuation
       character.

       Tcl_UniCharIsSpace tests if the character is a whitespace Unicode char‐
       acter.

       Tcl_UniCharIsUpper tests if the character is an uppercase Unicode char‐
       acter.

       Tcl_UniCharIsWordChar tests if the character is alphanumeric or a  con‐
       nector punctuation mark.


KEYWORDS
       unicode, classification



Tcl				      8.1		 Tcl_UniCharIsAlpha(3)

Tcl_UtfToUpper(3)	    Tcl Library Procedures	     Tcl_UtfToUpper(3)



______________________________________________________________________________

NAME
       Tcl_UniCharToUpper,	 Tcl_UniCharToLower,	   Tcl_UniCharToTitle,
       Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle - routines  for  manipu‐
       lating the case of Unicode characters and UTF-8 strings

SYNOPSIS
       #include <tcl.h>

       Tcl_UniChar
       Tcl_UniCharToUpper(ch)

       Tcl_UniChar
       Tcl_UniCharToLower(ch)

       Tcl_UniChar
       Tcl_UniCharToTitle(ch)

       int
       Tcl_UtfToUpper(str)

       int
       Tcl_UtfToLower(str)

       int
       Tcl_UtfToTitle(str)

ARGUMENTS
       int ch (in)	       The Unicode character to be converted.

       char *str (in/out)      Pointer	to  UTF-8  string  to  be converted in
			       place.
______________________________________________________________________________


DESCRIPTION
       The first three routines convert the case of individual Unicode charac‐
       ters:

       If ch represents a lower-case character, Tcl_UniCharToUpper returns the
       corresponding upper-case character.  If no upper-case character is  de‐
       fined, it returns the character unchanged.

       If  ch  represents  an upper-case character, Tcl_UniCharToLower returns
       the corresponding lower-case character.	If no lower-case character  is
       defined, it returns the character unchanged.

       If ch represents a lower-case character, Tcl_UniCharToTitle returns the
       corresponding title-case character.  If no title-case character is  de‐
       fined, it returns the corresponding upper-case character.  If no upper-
       case character is defined, it returns the character unchanged.	Title-
       case  is defined for a small number of characters that have a different
       appearance when they are at the beginning of a capitalized word.

       The next three routines convert the case of UTF-8 strings in  place  in
       memory:

       Tcl_UtfToUpper changes every UTF-8 character in str to upper-case.  Be‐
       cause changing the case of a character may change its  size,  the  byte
       offset  of  each	 character in the resulting string may differ from its
       original location.  Tcl_UtfToUpper writes a null byte at the end of the
       converted  string.  Tcl_UtfToUpper returns the new length of the string
       in bytes.  This new length is guaranteed to be no longer than the orig‐
       inal string length.

       Tcl_UtfToLower is the same as Tcl_UtfToUpper except it turns each char‐
       acter in the string into its lower-case equivalent.

       Tcl_UtfToTitle is the same as Tcl_UtfToUpper except it turns the	 first
       character  in the string into its title-case equivalent and all follow‐
       ing characters into their lower-case equivalents.


BUGS
       At this time, the case conversions are only  defined  for  the  Unicode
       plane  0 characters.  The result for Unicode characters above 0xFFFF is
       undefined, but - actually - only the lower 16  bits  of	the  character
       value is handled.


KEYWORDS
       utf, unicode, toupper, tolower, totitle, case



Tcl				      8.1		     Tcl_UtfToUpper(3)

Tcl_GetCwd(3)		    Tcl Library Procedures		 Tcl_GetCwd(3)



______________________________________________________________________________

NAME
       Tcl_GetCwd, Tcl_Chdir - manipulate the current working directory

SYNOPSIS
       #include <tcl.h>

       char *
       Tcl_GetCwd(interp, bufferPtr)

       int
       Tcl_Chdir(dirName)

ARGUMENTS
       Tcl_Interp *interp (in)		    Interpreter	 in which to report an
					    error, if any.

       Tcl_DString *bufferPtr (in/out)	    This dynamic  string  is  used  to
					    store  the	current working direc‐
					    tory.  At the time of the call  it
					    should  be	uninitialized or free.
					    The caller	must  eventually  call
					    Tcl_DStringFree  to	 free  up any‐
					    thing stored here.

       const char *dirName (in)		    File path in UTF-8 format.
______________________________________________________________________________


DESCRIPTION
       These procedures may be used to manipulate the current  working	direc‐
       tory  for  the  application.   They  provide C-level access to the same
       functionality as the Tcl pwd command.

       Tcl_GetCwd returns a pointer to a string specifying the current	direc‐
       tory,  or  NULL	if  the current directory could not be determined.  If
       NULL is returned, an error message is  left  in	the  interp's  result.
       Storage	for  the  result  string is allocated in bufferPtr; the caller
       must call Tcl_DStringFree() when the result is no longer	 needed.   The
       format of the path is UTF-8.

       Tcl_Chdir  changes  the	applications  current working directory to the
       value specified in dirName.  The format of the passed in string must be
       UTF-8.  The function returns -1 on error or 0 on success.


KEYWORDS
       pwd



Tcl				      8.1			 Tcl_GetCwd(3)

Tcl_UtfToUpper(3)	    Tcl Library Procedures	     Tcl_UtfToUpper(3)



______________________________________________________________________________

NAME
       Tcl_UniCharToUpper,	 Tcl_UniCharToLower,	   Tcl_UniCharToTitle,
       Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle - routines  for  manipu‐
       lating the case of Unicode characters and UTF-8 strings

SYNOPSIS
       #include <tcl.h>

       Tcl_UniChar
       Tcl_UniCharToUpper(ch)

       Tcl_UniChar
       Tcl_UniCharToLower(ch)

       Tcl_UniChar
       Tcl_UniCharToTitle(ch)

       int
       Tcl_UtfToUpper(str)

       int
       Tcl_UtfToLower(str)

       int
       Tcl_UtfToTitle(str)

ARGUMENTS
       int ch (in)	       The Unicode character to be converted.

       char *str (in/out)      Pointer	to  UTF-8  string  to  be converted in
			       place.
______________________________________________________________________________


DESCRIPTION
       The first three routines convert the case of individual Unicode charac‐
       ters:

       If ch represents a lower-case character, Tcl_UniCharToUpper returns the
       corresponding upper-case character.  If no upper-case character is  de‐
       fined, it returns the character unchanged.

       If  ch  represents  an upper-case character, Tcl_UniCharToLower returns
       the corresponding lower-case character.	If no lower-case character  is
       defined, it returns the character unchanged.

       If ch represents a lower-case character, Tcl_UniCharToTitle returns the
       corresponding title-case character.  If no title-case character is  de‐
       fined, it returns the corresponding upper-case character.  If no upper-
       case character is defined, it returns the character unchanged.	Title-
       case  is defined for a small number of characters that have a different
       appearance when they are at the beginning of a capitalized word.

       The next three routines convert the case of UTF-8 strings in  place  in
       memory:

       Tcl_UtfToUpper changes every UTF-8 character in str to upper-case.  Be‐
       cause changing the case of a character may change its  size,  the  byte
       offset  of  each	 character in the resulting string may differ from its
       original location.  Tcl_UtfToUpper writes a null byte at the end of the
       converted  string.  Tcl_UtfToUpper returns the new length of the string
       in bytes.  This new length is guaranteed to be no longer than the orig‐
       inal string length.

       Tcl_UtfToLower is the same as Tcl_UtfToUpper except it turns each char‐
       acter in the string into its lower-case equivalent.

       Tcl_UtfToTitle is the same as Tcl_UtfToUpper except it turns the	 first
       character  in the string into its title-case equivalent and all follow‐
       ing characters into their lower-case equivalents.


BUGS
       At this time, the case conversions are only  defined  for  the  Unicode
       plane  0 characters.  The result for Unicode characters above 0xFFFF is
       undefined, but - actually - only the lower 16  bits  of	the  character
       value is handled.


KEYWORDS
       utf, unicode, toupper, tolower, totitle, case



Tcl				      8.1		     Tcl_UtfToUpper(3)

Notifier(3)		    Tcl Library Procedures		   Notifier(3)



______________________________________________________________________________

NAME
       Tcl_CreateEventSource,	 Tcl_DeleteEventSource,	  Tcl_SetMaxBlockTime,
       Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert,  Tcl_GetCurrent‐
       Thread,	 Tcl_DeleteEvents,   Tcl_InitNotifier,	 Tcl_FinalizeNotifier,
       Tcl_WaitForEvent,  Tcl_AlertNotifier,   Tcl_SetTimer,   Tcl_ServiceAll,
       Tcl_ServiceEvent,  Tcl_GetServiceMode, Tcl_SetServiceMode, Tcl_Service‐
       ModeHook, Tcl_SetNotifier - the event queue and notifier interfaces

SYNOPSIS
       #include <tcl.h>

       void
       Tcl_CreateEventSource(setupProc, checkProc, clientData)

       void
       Tcl_DeleteEventSource(setupProc, checkProc, clientData)

       void
       Tcl_SetMaxBlockTime(timePtr)

       void
       Tcl_QueueEvent(evPtr, position)

       void
       Tcl_ThreadQueueEvent(threadId, evPtr, position)

       void
       Tcl_ThreadAlert(threadId)

       Tcl_ThreadId
       Tcl_GetCurrentThread()

       void
       Tcl_DeleteEvents(deleteProc, clientData)

       ClientData
       Tcl_InitNotifier()

       void
       Tcl_FinalizeNotifier(clientData)

       int
       Tcl_WaitForEvent(timePtr)

       void
       Tcl_AlertNotifier(clientData)

       void
       Tcl_SetTimer(timePtr)

       int
       Tcl_ServiceAll()

       int
       Tcl_ServiceEvent(flags)

       int
       Tcl_GetServiceMode()

       int
       Tcl_SetServiceMode(mode)

       void
       Tcl_ServiceModeHook(mode)

       void
       Tcl_SetNotifier(notifierProcPtr)

ARGUMENTS
       Tcl_EventSetupProc *setupProc (in)		  Procedure to	invoke
							  to prepare for event
							  wait		    in
							  Tcl_DoOneEvent.

       Tcl_EventCheckProc *checkProc (in)		  Procedure	   for
							  Tcl_DoOneEvent    to
							  invoke after waiting
							  for events.	Checks
							  to see if any events
							  have	occurred  and,
							  if so, queues them.

       ClientData clientData (in)			  Arbitrary   one-word
							  value to pass to se‐
							  tupProc,  checkProc,
							  or deleteProc.

       const Tcl_Time *timePtr (in)			  Indicates the	 maxi‐
							  mum  amount  of time
							  to   wait   for   an
							  event.     This   is
							  specified as an  in‐
							  terval  (how long to
							  wait), not an	 abso‐
							  lute	time  (when to
							  wakeup).    If   the
							  pointer   passed  to
							  Tcl_WaitForEvent  is
							  NULL, it means there
							  is no	 maximum  wait
							  time:	  wait forever
							  if necessary.

       Tcl_Event *evPtr (in)				  An event to  add  to
							  the	event	queue.
							  The storage for  the
							  event must have been
							  allocated   by   the
							  caller using Tcl_Al‐
							  loc or ckalloc.

       Tcl_QueuePosition position (in)			  Where to add the new
							  event	 in the queue:
							  TCL_QUEUE_TAIL,
							  TCL_QUEUE_HEAD,   or
							  TCL_QUEUE_MARK.

       Tcl_ThreadId threadId (in)			  A unique  identifier
							  for a thread.

       Tcl_EventDeleteProc *deleteProc (in)		  Procedure  to invoke
							  for	each	queued
							  event	 in  Tcl_Dele‐
							  teEvents.

       int flags (in)					  What types of events
							  to  service.	 These
							  flags are  the  same
							  as  those  passed to
							  Tcl_DoOneEvent.

       int mode (in)					  Indicates    whether
							  events   should   be
							  serviced by Tcl_Ser‐
							  viceAll.    Must  be
							  one	of    TCL_SER‐
							  VICE_NONE	    or
							  TCL_SERVICE_ALL.

       Tcl_NotifierProcs* notifierProcPtr (in)		  Structure  of	 func‐
							  tion	 pointers  de‐
							  scribing    notifier
							  procedures  that are
							  to replace the  ones
							  installed in the ex‐
							  ecutable.   See  RE‐
							  PLACING THE NOTIFIER
							  for details.
______________________________________________________________________________

INTRODUCTION
       The interfaces described here are used to customize the Tcl event loop.
       The two most common customizations are to add new sources of events and
       to merge Tcl's event loop with some other event loop, such as one  pro‐
       vided  by an application in which Tcl is embedded.  Each of these tasks
       is described in a separate section below.

       The procedures in this manual entry are	the  building  blocks  out  of
       which the Tcl event notifier is constructed.  The event notifier is the
       lowest layer in the Tcl event mechanism.	 It consists of three things:

       [1]    Event sources: these represent the ways in which events  can  be
	      generated.   For example, there is a timer event source that im‐
	      plements the Tcl_CreateTimerHandler procedure and the after com‐
	      mand,  and  there	 is  a	file  event source that implements the
	      Tcl_CreateFileHandler  procedure	on  Unix  systems.   An	 event
	      source must work with the notifier to detect events at the right
	      times, record them on the event  queue,  and  eventually	notify
	      higher-level  software  that they have occurred.	The procedures
	      Tcl_CreateEventSource,   Tcl_DeleteEventSource,	and   Tcl_Set‐
	      MaxBlockTime, Tcl_QueueEvent, and Tcl_DeleteEvents are used pri‐
	      marily by event sources.

       [2]    The event queue: for non-threaded applications, there is a  sin‐
	      gle queue for the whole application, containing events that have
	      been detected but not yet serviced.  Event sources place	events
	      onto  the queue so that they may be processed in order at appro‐
	      priate times during the event loop. The event queue guarantees a
	      fair  discipline	of event handling, so that no event source can
	      starve the others.  It also allows events to be saved  for  ser‐
	      vicing  at a future time.	 Threaded applications work in a simi‐
	      lar manner, except that there is a separate event queue for each
	      thread  containing  a  Tcl  interpreter.	Tcl_QueueEvent is used
	      (primarily by event sources) to add events to  the  event	 queue
	      and  Tcl_DeleteEvents  is	 used  to remove events from the queue
	      without	processing   them.    In   a   threaded	  application,
	      Tcl_QueueEvent  adds an event to the current thread's queue, and
	      Tcl_ThreadQueueEvent adds an event to  a	queue  in  a  specific
	      thread.

       [3]    The  event  loop: in order to detect and process events, the ap‐
	      plication enters a loop that waits for events to	occur,	places
	      them on the event queue, and then processes them.	 Most applica‐
	      tions will do this  by  calling  the  procedure  Tcl_DoOneEvent,
	      which is described in a separate manual entry.

       Most  Tcl applications need not worry about any of the internals of the
       Tcl notifier.  However, the notifier now has enough flexibility	to  be
       retargeted  either  for a new platform or to use an external event loop
       (such as the Motif event loop, when Tcl is embedded in a Motif applica‐
       tion).	The  procedures Tcl_WaitForEvent and Tcl_SetTimer are normally
       implemented by Tcl, but may be replaced with new versions  to  retarget
       the  notifier (the Tcl_InitNotifier, Tcl_AlertNotifier, Tcl_FinalizeNo‐
       tifier,	Tcl_Sleep,  Tcl_CreateFileHandler,  and	 Tcl_DeleteFileHandler
       must  also be replaced; see CREATING A NEW NOTIFIER below for details).
       The procedures  Tcl_ServiceAll,	Tcl_ServiceEvent,  Tcl_GetServiceMode,
       and Tcl_SetServiceMode are provided to help connect Tcl's event loop to
       an external event loop such as Motif's.

NOTIFIER BASICS
       The easiest way to understand how the notifier  works  is  to  consider
       what happens when Tcl_DoOneEvent is called.  Tcl_DoOneEvent is passed a
       flags argument that indicates what sort of events it is OK  to  process
       and   also   whether   or   not	to  block  if  no  events  are	ready.
       Tcl_DoOneEvent does the following things:

       [1]    Check the event queue to see if it contains any events that  can
	      be serviced.  If so, service the first possible event, remove it
	      from the queue, and return.  It does this	 by  calling  Tcl_Ser‐
	      viceEvent and passing in the flags argument.

       [2]    Prepare  to  block for an event.	To do this, Tcl_DoOneEvent in‐
	      vokes a setup procedure in each event source.  The event	source
	      will  perform  event-source specific initialization and possibly
	      call Tcl_SetMaxBlockTime to limit how long Tcl_WaitForEvent will
	      block if no new events occur.

       [3]    Call  Tcl_WaitForEvent.	This  procedure is implemented differ‐
	      ently on different platforms;  it waits for an event  to	occur,
	      based  on the information provided by the event sources.	It may
	      cause the application to block if timePtr specifies an  interval
	      other  than 0.  Tcl_WaitForEvent returns when something has hap‐
	      pened, such as a file becoming readable or the interval given by
	      timePtr  expiring.   If there are no events for Tcl_WaitForEvent
	      to wait for, so that it would block forever, then it returns im‐
	      mediately and Tcl_DoOneEvent returns 0.

       [4]    Call  a  check procedure in each event source.  The check proce‐
	      dure determines whether any events of interest  to  this	source
	      occurred.	 If so, the events are added to the event queue.

       [5]    Check  the event queue to see if it contains any events that can
	      be serviced.  If so, service the first possible event, remove it
	      from the queue, and return.

       [6]    See  if  there  are idle callbacks pending. If so, invoke all of
	      them and return.

       [7]    Either return 0 to indicate that no events  were	ready,	or  go
	      back to step [2] if blocking was requested by the caller.

CREATING A NEW EVENT SOURCE
       An  event  source consists of three procedures invoked by the notifier,
       plus additional C procedures that are invoked by higher-level  code  to
       arrange for event-driven callbacks.  The three procedures called by the
       notifier consist of the setup and  check	 procedures  described	above,
       plus  an	 additional procedure that is invoked when an event is removed
       from the event queue for servicing.

       The procedure Tcl_CreateEventSource creates a new  event	 source.   Its
       arguments specify the setup procedure and check procedure for the event
       source.	SetupProc should match the following prototype:

	      typedef void Tcl_EventSetupProc(
		      ClientData clientData,
		      int flags);

       The clientData argument will be the same as the clientData argument  to
       Tcl_CreateEventSource;  it is typically used to point to private infor‐
       mation managed by the event source.  The flags  argument	 will  be  the
       same as the flags argument passed to Tcl_DoOneEvent except that it will
       never be 0 (Tcl_DoOneEvent replaces 0 with TCL_ALL_EVENTS).  Flags  in‐
       dicates	what  kinds  of events should be considered; if the bit corre‐
       sponding to this event source is not set, the event source  should  re‐
       turn  immediately  without doing anything.  For example, the file event
       source checks for the TCL_FILE_EVENTS bit.

       SetupProc's job is to make sure that  the  application  wakes  up  when
       events  of  the	desired type occur.  This is typically done in a plat‐
       form-dependent fashion.	For example, under Unix an event source	 might
       call Tcl_CreateFileHandler; under Windows it might request notification
       with a Windows event.  For timer-driven event  sources  such  as	 timer
       events  or any polled event, the event source can call Tcl_SetMaxBlock‐
       Time to force the application to wake up after a specified time even if
       no  events have occurred.  If no event source calls Tcl_SetMaxBlockTime
       then Tcl_WaitForEvent will wait as long as necessary for	 an  event  to
       occur;  otherwise,  it  will only wait as long as the shortest interval
       passed to Tcl_SetMaxBlockTime by one of the event sources.  If an event
       source knows that it already has events ready to report, it can request
       a zero maximum block time.  For example, the setup procedure for the  X
       event source looks to see if there are events already queued.  If there
       are, it calls Tcl_SetMaxBlockTime with a 0 block time so that Tcl_Wait‐
       ForEvent	 does  not  block if there is no new data on the X connection.
       The timePtr argument to Tcl_WaitForEvent points to a structure that de‐
       scribes a time interval in seconds and microseconds:

	      typedef struct Tcl_Time {
		  long sec;
		  long usec;
	      } Tcl_Time;

       The usec field should be less than 1000000.

       Information  provided  to Tcl_SetMaxBlockTime is only used for the next
       call to Tcl_WaitForEvent; it is discarded  after	 Tcl_WaitForEvent  re‐
       turns.	The next time an event wait is done each of the event sources'
       setup procedures will be called again, and they can specify new	infor‐
       mation for that event wait.

       If   the	  application	uses   an  external  event  loop  rather  than
       Tcl_DoOneEvent, the event sources may need to call  Tcl_SetMaxBlockTime
       at other times.	For example, if a new event handler is registered that
       needs to poll for events, the event source may call Tcl_SetMaxBlockTime
       to  set the block time to zero to force the external event loop to call
       Tcl.  In this case, Tcl_SetMaxBlockTime invokes Tcl_SetTimer  with  the
       shortest	 interval  seen	 since	the  last  call	 to  Tcl_DoOneEvent or
       Tcl_ServiceAll.

       In addition to the generic procedure Tcl_SetMaxBlockTime,  other	 plat‐
       form-specific  procedures may also be available for setupProc, if there
       is additional information needed by Tcl_WaitForEvent on that  platform.
       For example, on Unix systems the Tcl_CreateFileHandler interface can be
       used to wait for file events.

       The second procedure provided by each event source is its check	proce‐
       dure,  indicated	 by  the  checkProc argument to Tcl_CreateEventSource.
       CheckProc must match the following prototype:

	      typedef void Tcl_EventCheckProc(
		      ClientData clientData,
		      int flags);

       The arguments to this procedure are the same as	those  for  setupProc.
       CheckProc  is invoked by Tcl_DoOneEvent after it has waited for events.
       Presumably at least one event source is now prepared to queue an event.
       Tcl_DoOneEvent  calls  each  of	the event sources in turn, so they all
       have a chance to queue any events that are ready.  The check  procedure
       does  two  things.   First,  it	must see if any events have triggered.
       Different event sources do this in different ways.

       If an event source's check procedure detects an interesting  event,  it
       must  add the event to Tcl's event queue.  To do this, the event source
       calls Tcl_QueueEvent.  The evPtr argument is a pointer to a dynamically
       allocated  structure  containing the event (see below for more informa‐
       tion on memory management issues).  Each event source  can  define  its
       own event structure with whatever information is relevant to that event
       source.	However, the first element of the structure must be  a	struc‐
       ture  of type Tcl_Event, and the address of this structure is used when
       communicating between the event source and the rest of the notifier.  A
       Tcl_Event has the following definition:

	      typedef struct {
		  Tcl_EventProc *proc;
		  struct Tcl_Event *nextPtr;
	      } Tcl_Event;

       The  event source must fill in the proc field of the event before call‐
       ing Tcl_QueueEvent.  The nextPtr is used to link together the events in
       the queue and should not be modified by the event source.

       An event may be added to the queue at any of three positions, depending
       on the position argument to Tcl_QueueEvent:

       TCL_QUEUE_TAIL	       Add the event at the back of the queue, so that
			       all  other  pending  events  will  be  serviced
			       first.  This is almost always the  right	 place
			       for new events.

       TCL_QUEUE_HEAD	       Add  the	 event	at  the front of the queue, so
			       that it	will  be  serviced  before  all	 other
			       queued events.

       TCL_QUEUE_MARK	       Add the event at the front of the queue, unless
			       there are other events at the front whose posi‐
			       tion  is	 TCL_QUEUE_MARK;   if  so, add the new
			       event  just  after  all	other	TCL_QUEUE_MARK
			       events.	 This value of position is used to in‐
			       sert an ordered sequence of events at the front
			       of  the	queue,	such  as a series of Enter and
			       Leave events synthesized during a grab  or  un‐
			       grab operation in Tk.

       When it is time to handle an event from the queue (steps 1 and 4 above)
       Tcl_ServiceEvent will invoke the proc specified	in  the	 first	queued
       Tcl_Event structure.  Proc must match the following prototype:

	      typedef int Tcl_EventProc(
		      Tcl_Event *evPtr,
		      int flags);

       The first argument to proc is a pointer to the event, which will be the
       same as the first argument to the Tcl_QueueEvent call  that  added  the
       event  to the queue.  The second argument to proc is the flags argument
       for the current call to Tcl_ServiceEvent;  this is used	by  the	 event
       source to return immediately if its events are not relevant.

       It is up to proc to handle the event, typically by invoking one or more
       Tcl commands or C-level callbacks.  Once the event source has  finished
       handling	 the  event it returns 1 to indicate that the event can be re‐
       moved from the queue.  If for some reason the event source decides that
       the  event  cannot be handled at this time, it may return 0 to indicate
       that the event should be deferred for processing later;	in  this  case
       Tcl_ServiceEvent	 will go on to the next event in the queue and attempt
       to service it.  There are several reasons why an event source might de‐
       fer an event.  One possibility is that events of this type are excluded
       by the flags argument.  For example, the file event source will	always
       return 0 if the TCL_FILE_EVENTS bit is not set in flags.	 Another exam‐
       ple of deferring events happens in Tk if Tk_RestrictEvents has been in‐
       voked to defer certain kinds of window events.

       When  proc  returns  1, Tcl_ServiceEvent will remove the event from the
       event queue and free its storage.  Note that the storage for  an	 event
       must be allocated by the event source (using Tcl_Alloc or the Tcl macro
       ckalloc) before	calling	 Tcl_QueueEvent,  but  it  will	 be  freed  by
       Tcl_ServiceEvent, not by the event source.

       Threaded	 applications work in a similar manner, except that there is a
       separate event queue for each  thread  containing  a  Tcl  interpreter.
       Calling	Tcl_QueueEvent in a multithreaded application adds an event to
       the current thread's queue.  To add an event to another thread's queue,
       use  Tcl_ThreadQueueEvent.  Tcl_ThreadQueueEvent accepts as an argument
       a Tcl_ThreadId argument, which uniquely identifies a thread  in	a  Tcl
       application.   To  obtain  the Tcl_ThreadId for the current thread, use
       the Tcl_GetCurrentThread procedure.  (A thread would then need to  pass
       this  identifier	 to  other threads for those threads to be able to add
       events to its queue.)  After adding an event to another thread's queue,
       you  then  typically  need  to  call  Tcl_ThreadAlert to “wake up” that
       thread's notifier to alert it to the new event.

       Tcl_DeleteEvents can be used to explicitly remove one  or  more	events
       from  the  event	 queue.	 Tcl_DeleteEvents calls proc for each event in
       the queue, deleting those for with the procedure returns 1.  Events for
       which the procedure returns 0 are left in the queue.  Proc should match
       the following prototype:

	      typedef int Tcl_EventDeleteProc(
		      Tcl_Event *evPtr,
		      ClientData clientData);

       The clientData argument will be the same as the clientData argument  to
       Tcl_DeleteEvents;  it is typically used to point to private information
       managed by the event source.  The evPtr will point to the next event in
       the queue.

       Tcl_DeleteEventSource  deletes  an event source.	 The setupProc, check‐
       Proc, and clientData arguments must exactly match those provided to the
       Tcl_CreateEventSource  for  the event source to be deleted.  If no such
       source exists, Tcl_DeleteEventSource has no effect.

CREATING A NEW NOTIFIER
       The notifier consists of all the procedures described  in  this	manual
       entry,  plus  Tcl_DoOneEvent  and Tcl_Sleep, which are available on all
       platforms, and Tcl_CreateFileHandler and	 Tcl_DeleteFileHandler,	 which
       are  Unix-specific.  Most of these procedures are generic, in that they
       are the same for all notifiers.	However, none of  the  procedures  are
       notifier-dependent:   Tcl_InitNotifier,	Tcl_AlertNotifier,  Tcl_Final‐
       izeNotifier, Tcl_SetTimer, Tcl_Sleep, Tcl_WaitForEvent, Tcl_CreateFile‐
       Handler,	 Tcl_DeleteFileHandler	and Tcl_ServiceModeHook.  To support a
       new platform or to integrate Tcl	 with  an  application-specific	 event
       loop, you must write new versions of these procedures.

       Tcl_InitNotifier initializes the notifier state and returns a handle to
       the notifier state.  Tcl calls this procedure when initializing	a  Tcl
       interpreter.   Similarly, Tcl_FinalizeNotifier shuts down the notifier,
       and is called by Tcl_Finalize when shutting down a Tcl interpreter.

       Tcl_WaitForEvent is the lowest-level procedure in the notifier;	it  is
       responsible  for	 waiting  for an “interesting” event to occur or for a
       given time to elapse.  Before Tcl_WaitForEvent is invoked, each of  the
       event sources' setup procedure will have been invoked.  The timePtr ar‐
       gument to Tcl_WaitForEvent gives the  maximum  time  to	block  for  an
       event,  based  on calls to Tcl_SetMaxBlockTime made by setup procedures
       and on other information (such as the TCL_DONT_WAIT bit in flags).

       Ideally, Tcl_WaitForEvent should only wait for an event	to  occur;  it
       should  not actually process the event in any way.  Later on, the event
       sources will process the raw events and create Tcl_Events on the	 event
       queue  in their checkProc procedures.  However, on some platforms (such
       as Windows) this is not possible; events may be processed in  Tcl_Wait‐
       ForEvent, including queuing Tcl_Events and more (for example, callbacks
       for native widgets may be invoked).  The return	value  from  Tcl_Wait‐
       ForEvent	 must  be  either  0,  1, or -1.  On platforms such as Windows
       where events get processed in Tcl_WaitForEvent, a  return  value	 of  1
       means  that  there  may be more events still pending that have not been
       processed.  This is a sign to the caller that it	 must  call  Tcl_Wait‐
       ForEvent	 again if it wants all pending events to be processed. A 0 re‐
       turn value means that calling Tcl_WaitForEvent again will not have  any
       effect:	either	this  is  a platform where Tcl_WaitForEvent only waits
       without doing any event processing, or Tcl_WaitForEvent knows for  sure
       that  there  are	 no additional events to process (e.g. it returned be‐
       cause the time elapsed).	 Finally, a return value of -1 means that  the
       event loop is no longer operational and the application should probably
       unwind and terminate.  Under Windows this happens when a	 WM_QUIT  mes‐
       sage  is	 received;  under  Unix it happens when Tcl_WaitForEvent would
       have waited forever because there were no active event sources and  the
       timeout was infinite.

       Tcl_AlertNotifier  is  used  in multithreaded applications to allow any
       thread to “wake up” the notifier to alert  it  to  new  events  on  its
       queue.	Tcl_AlertNotifier  requires as an argument the notifier handle
       returned by Tcl_InitNotifier.

       If the notifier will be used with an external event loop, then it  must
       also  support  the  Tcl_SetTimer interface.  Tcl_SetTimer is invoked by
       Tcl_SetMaxBlockTime whenever the maximum blocking  time	has  been  re‐
       duced.	Tcl_SetTimer should arrange for the external event loop to in‐
       voke Tcl_ServiceAll after the specified interval even if no events have
       occurred.  This interface is needed because Tcl_WaitForEvent is not in‐
       voked when there is an external event loop.  If the notifier will  only
       be used from Tcl_DoOneEvent, then Tcl_SetTimer need not do anything.

       Tcl_ServiceModeHook  is	called	by the platform-independent portion of
       the notifier when client code makes a call to Tcl_SetServiceMode.  This
       hook  is	 provided  to  support	operating systems that require special
       event handling when the application is in a modal loop (the Windows no‐
       tifier, for instance, uses this hook to create a communication window).

       On  Unix systems, the file event source also needs support from the no‐
       tifier.	The file event source consists	of  the	 Tcl_CreateFileHandler
       and  Tcl_DeleteFileHandler  procedures,	which  are  described  in  the
       Tcl_CreateFileHandler manual page.

       The Tcl_Sleep and Tcl_DoOneEvent interfaces are described in their  re‐
       spective manual pages.

       The  easiest way to create a new notifier is to look at the code for an
       existing notifier, such as the files unix/tclUnixNotfy.c or win/tclWin‐
       Notify.c in the Tcl source distribution.

REPLACING THE NOTIFIER
       A notifier that has been written according to the conventions above can
       also be installed in a running process in place of the  standard	 noti‐
       fier.   This  mechanism is used so that a single executable can be used
       (with the standard notifier) as a stand-alone program and reused	 (with
       a  replacement notifier in a loadable extension) as an extension to an‐
       other program, such as a Web browser plugin.

       To do this, the extension makes a call  to  Tcl_SetNotifier  passing  a
       pointer	to  a Tcl_NotifierProcs data structure.	 The structure has the
       following layout:

	      typedef struct Tcl_NotifierProcs {
		  Tcl_SetTimerProc *setTimerProc;
		  Tcl_WaitForEventProc *waitForEventProc;
		  Tcl_CreateFileHandlerProc *createFileHandlerProc;
		  Tcl_DeleteFileHandlerProc *deleteFileHandlerProc;
		  Tcl_InitNotifierProc *initNotifierProc;
		  Tcl_FinalizeNotifierProc *finalizeNotifierProc;
		  Tcl_AlertNotifierProc *alertNotifierProc;
		  Tcl_ServiceModeHookProc *serviceModeHookProc;
	      } Tcl_NotifierProcs;

       Following the call  to  Tcl_SetNotifier,	 the  pointers	given  in  the
       Tcl_NotifierProcs  structure  replace  whatever	notifier  had been in‐
       stalled in the process.

       It is extraordinarily unwise to replace a running  notifier.  Normally,
       Tcl_SetNotifier	should be called at process initialization time before
       the first call to Tcl_InitNotifier.

EXTERNAL EVENT LOOPS
       The notifier interfaces are designed so that Tcl can be	embedded  into
       applications  that  have	 their own private event loops.	 In this case,
       the application does not call Tcl_DoOneEvent except in the case of  re‐
       cursive	event loops such as calls to the Tcl commands update or vwait.
       Most of the time is spent in the external event loop  of	 the  applica‐
       tion.   In  this	 case the notifier must arrange for the external event
       loop to call back into Tcl when something happens on  the  various  Tcl
       event  sources.	 These	callbacks  should  arrange for appropriate Tcl
       events to be placed on the Tcl event queue.

       Because the external event loop is not calling Tcl_DoOneEvent on a reg‐
       ular basis, it is up to the notifier to arrange for Tcl_ServiceEvent to
       be called whenever events are pending on the Tcl event queue.  The eas‐
       iest  way  to  do  this	is to invoke Tcl_ServiceAll at the end of each
       callback from the external event loop.  This will ensure	 that  all  of
       the  event  sources are polled, any queued events are serviced, and any
       pending idle handlers are processed before returning control to the ap‐
       plication.  In addition, event sources that need to poll for events can
       call Tcl_SetMaxBlockTime to force the external event loop to  call  Tcl
       even if no events are available on the system event queue.

       As  a  side  effect  of processing events detected in the main external
       event loop, Tcl may invoke Tcl_DoOneEvent to start  a  recursive	 event
       loop  in	 commands like vwait.  Tcl_DoOneEvent will invoke the external
       event loop, which will result in callbacks as described in the  preced‐
       ing  paragraph, which will result in calls to Tcl_ServiceAll.  However,
       in these cases it is undesirable to service events  in  Tcl_ServiceAll.
       Servicing  events there is unnecessary because control will immediately
       return to the external event loop and hence  to	Tcl_DoOneEvent,	 which
       can service the events itself.  Furthermore, Tcl_DoOneEvent is supposed
       to service only a single event, whereas	Tcl_ServiceAll	normally  ser‐
       vices  all  pending  events.   To handle this situation, Tcl_DoOneEvent
       sets a flag for Tcl_ServiceAll that causes it to return without servic‐
       ing  any	 events.  This flag is called the service mode; Tcl_DoOneEvent
       restores it to its previous value before it returns.

       In some cases, however, it may be necessary for Tcl_ServiceAll to  ser‐
       vice  events  even  when it has been invoked from Tcl_DoOneEvent.  This
       happens when there is yet another recursive event loop invoked  via  an
       event  handler  called by Tcl_DoOneEvent (such as one that is part of a
       native widget).	In this case, Tcl_DoOneEvent may not have a chance  to
       service	events so Tcl_ServiceAll must service them all.	 Any recursive
       event loop that calls an external event loop rather than Tcl_DoOneEvent
       must  reset  the	 service  mode	so  that  all  events get processed in
       Tcl_ServiceAll.	This is done by invoking the Tcl_SetServiceMode proce‐
       dure.   If Tcl_SetServiceMode is passed TCL_SERVICE_NONE, then calls to
       Tcl_ServiceAll will return immediately without processing  any  events.
       If Tcl_SetServiceMode is passed TCL_SERVICE_ALL, then calls to Tcl_Ser‐
       viceAll will behave normally.  Tcl_SetServiceMode returns the  previous
       value  of the service mode, which should be restored when the recursive
       loop exits.  Tcl_GetServiceMode returns the current value of  the  ser‐
       vice mode.

SEE ALSO
       Tcl_CreateFileHandler(3),    Tcl_DeleteFileHandler(3),	 Tcl_Sleep(3),
       Tcl_DoOneEvent(3), Thread(3)

KEYWORDS
       event, notifier, event queue, event sources, file events, timer,	 idle,
       service mode, threads



Tcl				      8.1			   Notifier(3)

NRE(3)			    Tcl Library Procedures			NRE(3)



______________________________________________________________________________

NAME
       Tcl_NRCreateCommand,  Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv,
       Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback - Non-Recursive (stack‐
       less) evaluation of Tcl scripts.

SYNOPSIS
       #include <tcl.h>

       Tcl_Command
       Tcl_NRCreateCommand(interp, cmdName, proc, nreProc, clientData,
			   deleteProc)

       int
       Tcl_NRCallObjProc(interp, nreProc, clientData, objc, objv)

       int
       Tcl_NREvalObj(interp, objPtr, flags)

       int
       Tcl_NREvalObjv(interp, objc, objv, flags)

       int
       Tcl_NRCmdSwap(interp, cmd, objc, objv, flags)

       int
       Tcl_NRExprObj(interp, objPtr, resultPtr)

       void
       Tcl_NRAddCallback(interp, postProcPtr, data0, data1, data2, data3)

ARGUMENTS
       Tcl_Interp *interp (in)		       The relevant Interpreter.

       const char *cmdName (in)		       Name of the command to create.

       Tcl_ObjCmdProc *proc (in)	       Called  in  order to evaluate a
					       command.	 Is often just a small
					       wrapper that uses Tcl_NRCallOb‐
					       jProc to call nreProc  using  a
					       new trampoline.	Behaves in the
					       same way as the	proc  argument
					       to      Tcl_CreateObjCommand(3)
					       (q.v.).

       Tcl_ObjCmdProc *nreProc (in)	       Called instead of proc  when  a
					       trampoline is already in use.

       ClientData clientData (in)	       Arbitrary one-word value passed
					       to  proc,  nreProc,  deleteProc
					       and objProc.

       Tcl_CmdDeleteProc *deleteProc (in/out)  Called	 before	  cmdName   is
					       deleted from  the  interpreter,
					       allowing	 for  command-specific
					       cleanup. May be NULL.

       int objc (in)			       Number of items in objv.

       Tcl_Obj **objv (in)		       Words in the command.

       Tcl_Obj *objPtr (in)		       A script or expression to eval‐
					       uate.

       int flags (in)			       As described for Tcl_EvalObjv.

       Tcl_Command cmd (in)		       Token to use instead of one de‐
					       rived from the  first  word  of
					       objv  in	 order	to  evaluate a
					       command.

       Tcl_Obj *resultPtr (out)		       Pointer to an unshared  Tcl_Obj
					       where the result of the evalua‐
					       tion is stored  if  the	return
					       code is TCL_OK.

       Tcl_NRPostProc *postProcPtr (in)	       A function to push.

       ClientData data0 (in)

       ClientData data1 (in)

       ClientData data2 (in)

       ClientData data3 (in)		       data0  through  data3  are four
					       one-word values	that  will  be
					       passed  to  the function desig‐
					       nated by postProcPtr when it is
					       invoked.
______________________________________________________________________________

DESCRIPTION
       These  functions provide an interface to the function stack that an in‐
       terpreter iterates through to evaluate commands.	 The routine behind  a
       command	is implemented by an initial function and any additional func‐
       tions that the routine pushes onto the stack as it progresses.  The in‐
       terpreter itself pushes functions onto the stack to react to the end of
       a routine and to exercise other forms of control such as switching  be‐
       tween  in-progress  stacks and the evaluation of other scripts at addi‐
       tional levels without adding frames to the C stack.  To execute a  rou‐
       tine,  the  initial function for the routine is called and then a small
       bit of code called a trampoline iteratively  takes  functions  off  the
       stack  and calls them, using the value of the last call as the value of
       the routine.

       Tcl_NRCallObjProc calls nreProc using a new trampoline.

       Tcl_NRCreateCommand, an alternative to  Tcl_CreateObjCommand,  resolves
       cmdName,	 which	may contain namespace qualifiers, relative to the cur‐
       rent namespace, creates a command by that name, and returns a token for
       the  command  which  may be used in subsequent calls to Tcl_GetCommand‐
       Name.  Except for a few cases noted below any existing command  by  the
       same  name  is  first  deleted.	 If  interp is in the process of being
       deleted Tcl_NRCreateCommand does	 not  create  any  command,  does  not
       delete any command, and returns NULL.

       Tcl_NREvalObj pushes a function that is like Tcl_EvalObjEx but consumes
       no space on the C stack.

       Tcl_NREvalObjv pushes a function that is like Tcl_EvalObjv but consumes
       no space on the C stack.

       Tcl_NRCmdSwap  is like Tcl_NREvalObjv, but uses cmd, a token previously
       returned by Tcl_CreateObjCommand or Tcl_GetCommandFromObj,  instead  of
       resolving the first word of objv.

       Tcl_NRExprObj  pushes a function that evaluates objPtr as an expression
       in the same manner as Tcl_ExprObj but without consuming space on the  C
       stack.

       All  of	the  functions	return TCL_OK if the evaluation of the script,
       command, or expression has been scheduled successfully.	Otherwise (for
       example	if the command name cannot be resolved), they return TCL_ERROR
       and store a message as the interpreter's result.

       Tcl_NRAddCallback pushes postProcPtr.  The signature for Tcl_NRPostProc
       is:

	      typedef int
	      Tcl_NRPostProc(
		      ClientData data[],
		      Tcl_Interp *interp,
		      int result);

       data  is	 a pointer to an array containing data0 through data3.	result
       is the value returned by the previous function  implementing  part  the
       routine.

EXAMPLE
       The following command uses Tcl_EvalObjEx, which consumes space on the C
       stack, to evalute a script:

	      int
	      TheCmdOldObjProc(
		  ClientData clientData,
		  Tcl_Interp *interp,
		  int objc,
		  Tcl_Obj *const objv[])
	      {
		  int result;
		  Tcl_Obj *objPtr;

		  ... preparation ...

		  result = Tcl_EvalObjEx(interp, objPtr, 0);

		  ... postprocessing ...

		  return result;
	      }
	      Tcl_CreateObjCommand(interp, "theCommand",
		      TheCmdOldObjProc, clientData, TheCmdDeleteProc);

       To avoid consuming space on the C stack, TheCmdOldObjProc is renamed to
       TheCmdNRObjProc	and  the  postprocessing step is split into a separate
       function, TheCmdPostProc, which is  pushed  onto	 the  function	stack.
       Tcl_EvalObjEx  is  replaced with Tcl_NREvalObj, which uses a trampoline
       instead of consuming space on the C stack.  A  new  version  of	TheCm‐
       dOldObjProc  is	just  a	 a wrapper that uses Tcl_NRCallObjProc to call
       TheCmdNRObjProc:

	      int
	      TheCmdOldObjProc(
		  ClientData clientData,
		  Tcl_Interp *interp,
		  int objc,
		  Tcl_Obj *const objv[])
	      {
		  return Tcl_NRCallObjProc(interp, TheCmdNRObjProc,
			  clientData, objc, objv);
	      }

	      int
	      TheCmdNRObjProc
		  ClientData clientData,
		  Tcl_Interp *interp,
		  int objc,
		  Tcl_Obj *const objv[])
	      {
		  Tcl_Obj *objPtr;

		  ... preparation ...

		  Tcl_NRAddCallback(interp, TheCmdPostProc,
			  data0, data1, data2, data3);
		  /* data0 .. data3 are up to four one-word items to
		   * pass to the postprocessing procedure */

		  return Tcl_NREvalObj(interp, objPtr, 0);
	      }

	      int
	      TheCmdNRPostProc(
		  ClientData data[],
		  Tcl_Interp *interp,
		  int result)
	      {
		  /* data[0] .. data[3] are the four words of data
		   * passed to Tcl_NRAddCallback */

		  ... postprocessing ...

		  return result;
	      }

       Any function comprising a routine can push other functions,  making  it
       possible implement looping and sequencing constructs using the function
       stack.

SEE ALSO
       Tcl_CreateCommand(3),	Tcl_CreateObjCommand(3),     Tcl_EvalObjEx(3),
       Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)

KEYWORDS
       stackless,  nonrecursive,  execute,  command,  global,  value,  result,
       script

COPYRIGHT
       Copyright © 2008 Kevin B. Kenny.	 Copyright © 2018 Nathan Coulter.



Tcl				      8.6				NRE(3)

Tcl_CreateObjCommand(3)	    Tcl Library Procedures     Tcl_CreateObjCommand(3)



______________________________________________________________________________

NAME
       Tcl_CreateObjCommand,   Tcl_DeleteCommand,  Tcl_DeleteCommandFromToken,
       Tcl_GetCommandInfo,  Tcl_GetCommandInfoFromToken,   Tcl_SetCommandInfo,
       Tcl_SetCommandInfoFromToken,   Tcl_GetCommandName,  Tcl_GetCommandFull‐
       Name, Tcl_GetCommandFromObj - implement new commands in C

SYNOPSIS
       #include <tcl.h>

       Tcl_Command
       Tcl_CreateObjCommand(interp, cmdName, proc, clientData, deleteProc)

       int
       Tcl_DeleteCommand(interp, cmdName)

       int
       Tcl_DeleteCommandFromToken(interp, token)

       int
       Tcl_GetCommandInfo(interp, cmdName, infoPtr)

       int
       Tcl_SetCommandInfo(interp, cmdName, infoPtr)

       int
       Tcl_GetCommandInfoFromToken(token, infoPtr)

       int
       Tcl_SetCommandInfoFromToken(token, infoPtr)

       const char *
       Tcl_GetCommandName(interp, token)

       void
       Tcl_GetCommandFullName(interp, token, objPtr)

       Tcl_Command
       Tcl_GetCommandFromObj(interp, objPtr)

ARGUMENTS
       Tcl_Interp *interp (in)			   Interpreter	in  which   to
						   create  a  new  command  or
						   that contains a command.

       const char *cmdName (in)			   Name of command.

       Tcl_ObjCmdProc *proc (in)		   Implementation of  the  new
						   command:   proc   will   be
						   called whenever cmdName  is
						   invoked as a command.

       ClientData clientData (in)		   Arbitrary one-word value to
						   pass	   to	  proc	   and
						   deleteProc.

       Tcl_CmdDeleteProc *deleteProc (in)	   Procedure  to  call	before
						   cmdName is deleted from the
						   interpreter;	  allows   for
						   command-specific   cleanup.
						   If  NULL, then no procedure
						   is called before  the  com‐
						   mand is deleted.

       Tcl_Command token (in)			   Token for command, returned
						   by	previous    call    to
						   Tcl_CreateObjCommand.   The
						   command must not have  been
						   deleted.

       Tcl_CmdInfo *infoPtr (in/out)		   Pointer  to	structure con‐
						   taining various information
						   about a Tcl command.

       Tcl_Obj *objPtr (in)			   Value  containing  the name
						   of a Tcl command.
______________________________________________________________________________

DESCRIPTION
       Tcl_CreateObjCommand defines a new command in interp and associates  it
       with procedure proc such that whenever name is invoked as a Tcl command
       (e.g., via a call to Tcl_EvalObjEx) the Tcl interpreter will call  proc
       to process the command.

       Tcl_CreateObjCommand  deletes any existing command name already associ‐
       ated with the interpreter (however see below for an exception where the
       existing	 command is not deleted).  It returns a token that may be used
       to refer to the command in subsequent calls to Tcl_GetCommandName.   If
       name contains any :: namespace qualifiers, then the command is added to
       the specified namespace; otherwise the command is added to  the	global
       namespace.   If	Tcl_CreateObjCommand is called for an interpreter that
       is in the process of being deleted, then it does not create a new  com‐
       mand  and  it returns NULL.  proc should have arguments and result that
       match the type Tcl_ObjCmdProc:

	      typedef int Tcl_ObjCmdProc(
		      ClientData clientData,
		      Tcl_Interp *interp,
		      int objc,
		      Tcl_Obj *const objv[]);

       When proc is invoked, the clientData  and  interp  parameters  will  be
       copies  of  the clientData and interp arguments given to Tcl_CreateObj‐
       Command.	 Typically, clientData points to an application-specific  data
       structure  that	describes what to do when the command procedure is in‐
       voked. Objc and objv describe the arguments to the command, objc giving
       the  number  of	argument  values (including the command name) and objv
       giving the values of the arguments.  The objv array will	 contain  objc
       values,	pointing  to the argument values.  Unlike argv[argv] used in a
       string-based command procedure, objv[objc] will not contain NULL.

       Additionally, when proc is invoked, it must not modify the contents  of
       the  objv  array	 by assigning new pointer values to any element of the
       array (for example, objv[2] = NULL) because this will cause  memory  to
       be lost and the runtime stack to be corrupted.  The const in the decla‐
       ration of objv will cause ANSI-compliant compilers to report  any  such
       attempted  assignment as an error.  However, it is acceptable to modify
       the internal representation of any individual value argument.  For  in‐
       stance,	the  user  may call Tcl_GetIntFromObj on objv[2] to obtain the
       integer representation of that value; that call may change the type  of
       the  value  that	 objv[2]  points at, but will not change where objv[2]
       points.

       proc must return an integer code	 that  is  either  TCL_OK,  TCL_ERROR,
       TCL_RETURN,  TCL_BREAK, or TCL_CONTINUE.	 See the Tcl overview man page
       for details on what these codes mean.  Most normal commands  will  only
       return  TCL_OK  or  TCL_ERROR.	In addition, if proc needs to return a
       non-empty result, it can call Tcl_SetObjResult to set the interpreter's
       result.	 In  the case of a TCL_OK return code this gives the result of
       the command, and in the case of TCL_ERROR this gives an error  message.
       Before  invoking	 a command procedure, Tcl_EvalObjEx sets interpreter's
       result to point to a value representing an empty string, so simple com‐
       mands can return an empty result by doing nothing at all.

       The  contents of the objv array belong to Tcl and are not guaranteed to
       persist once proc returns: proc should not modify them.	Call Tcl_SetO‐
       bjResult if you want to return something from the objv array.

       Ordinarily,  Tcl_CreateObjCommand deletes any existing command name al‐
       ready associated with the interpreter.  However, if the	existing  com‐
       mand was created by a previous call to Tcl_CreateCommand, Tcl_CreateOb‐
       jCommand does not delete the command but instead arranges for  the  Tcl
       interpreter  to	call  the  Tcl_ObjCmdProc proc in the future.  The old
       string-based Tcl_CmdProc associated with the command  is	 retained  and
       its  address  can  be  obtained by subsequent Tcl_GetCommandInfo calls.
       This is done for backwards compatibility.

       DeleteProc will be invoked when (if) name is deleted.  This  can	 occur
       through	a  call	 to  Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, or
       Tcl_DeleteInterp, or by replacing name in another call to Tcl_CreateOb‐
       jCommand.   DeleteProc  is  invoked  before the command is deleted, and
       gives the application an opportunity to release any structures  associ‐
       ated  with  the	command.   DeleteProc should have arguments and result
       that match the type Tcl_CmdDeleteProc:

	      typedef void Tcl_CmdDeleteProc(
		      ClientData clientData);

       The clientData argument will be the same	 as  the  clientData  argument
       passed to Tcl_CreateObjCommand.

       Tcl_DeleteCommand  deletes  a command from a command interpreter.  Once
       the call completes, attempts to invoke cmdName in interp will result in
       errors.	 If  cmdName  is  not  bound  as  a  command  in  interp  then
       Tcl_DeleteCommand does nothing and returns -1;  otherwise it returns 0.
       There  are no restrictions on cmdName:  it may refer to a built-in com‐
       mand, an application-specific command, or a  Tcl	 procedure.   If  name
       contains	 any  :: namespace qualifiers, the command is deleted from the
       specified namespace.

       Given a token returned by Tcl_CreateObjCommand,	Tcl_DeleteCommandFrom‐
       Token deletes the command from a command interpreter.  It will delete a
       command even if that command has been  renamed.	 Once  the  call  com‐
       pletes, attempts to invoke the command in interp will result in errors.
       If the command corresponding to token has already been deleted from in‐
       terp  then  Tcl_DeleteCommand does nothing and returns -1; otherwise it
       returns 0.

       Tcl_GetCommandInfo checks to see whether its cmdName argument exists as
       a  command  in  interp.	cmdName may include :: namespace qualifiers to
       identify a command in a particular namespace.  If the  command  is  not
       found,  then  it	 returns 0.  Otherwise it places information about the
       command in the Tcl_CmdInfo structure pointed to by infoPtr and  returns
       1.  A Tcl_CmdInfo structure has the following fields:

	      typedef struct Tcl_CmdInfo {
		  int isNativeObjectProc;
		  Tcl_ObjCmdProc *objProc;
		  ClientData objClientData;
		  Tcl_CmdProc *proc;
		  ClientData clientData;
		  Tcl_CmdDeleteProc *deleteProc;
		  ClientData deleteData;
		  Tcl_Namespace *namespacePtr;
	      } Tcl_CmdInfo;

       The  isNativeObjectProc	field  has the value 1 if Tcl_CreateObjCommand
       was called to register the command; it is 0 if  only  Tcl_CreateCommand
       was  called.   It allows a program to determine whether it is faster to
       call objProc or proc: objProc is normally faster if  isNativeObjectProc
       has  the	 value	1.  The fields objProc and objClientData have the same
       meaning as the proc and clientData arguments  to	 Tcl_CreateObjCommand;
       they  hold information about the value-based command procedure that the
       Tcl interpreter calls to implement the command.	The  fields  proc  and
       clientData  hold	 information  about the string-based command procedure
       that implements the command.  If Tcl_CreateCommand was called for  this
       command,	 this is the procedure passed to it; otherwise, this is a com‐
       patibility procedure registered	by  Tcl_CreateObjCommand  that	simply
       calls  the  command's value-based procedure after converting its string
       arguments to Tcl values.	 The field deleteData is the ClientData	 value
       to  pass	 to deleteProc;	 it is normally the same as clientData but may
       be set independently using the Tcl_SetCommandInfo procedure.  The field
       namespacePtr  holds  a  pointer	to the Tcl_Namespace that contains the
       command.

       Tcl_GetCommandInfoFromToken is identical to  Tcl_GetCommandInfo	except
       that  it	 uses  a  command  token returned from Tcl_CreateObjCommand in
       place of the command name.  If the token parameter is NULL, it  returns
       0; otherwise, it returns 1 and fills in the structure designated by in‐
       foPtr.

       Tcl_SetCommandInfo is used to modify the procedures and ClientData val‐
       ues  associated	with a command.	 Its cmdName argument is the name of a
       command in interp.  cmdName may	include	 ::  namespace	qualifiers  to
       identify a command in a particular namespace.  If this command does not
       exist then Tcl_SetCommandInfo returns 0.	 Otherwise, it copies the  in‐
       formation from *infoPtr to Tcl's internal structure for the command and
       returns 1.

       Tcl_SetCommandInfoFromToken is identical to  Tcl_SetCommandInfo	except
       that  it	 takes a command token as returned by Tcl_CreateObjCommand in‐
       stead of the command name.  If the token parameter is NULL, it  returns
       0.   Otherwise, it copies the information from *infoPtr to Tcl's inter‐
       nal structure for the command and returns 1.

       Note that Tcl_SetCommandInfo and Tcl_SetCommandInfoFromToken both allow
       the ClientData for a command's deletion procedure to be given a differ‐
       ent value than the ClientData for its command procedure.

       Note that neither  Tcl_SetCommandInfo  nor  Tcl_SetCommandInfoFromToken
       will  change  a	command's  namespace.  Use Tcl_Eval to call the rename
       command to do that.

       Tcl_GetCommandName provides a mechanism for tracking commands that have
       been  renamed.  Given a token returned by Tcl_CreateObjCommand when the
       command was created, Tcl_GetCommandName returns the string name of  the
       command.	  If  the  command has been renamed since it was created, then
       Tcl_GetCommandName returns the current name.  This name	does  not  in‐
       clude  any :: namespace qualifiers.  The command corresponding to token
       must not have been deleted.  The string returned by  Tcl_GetCommandName
       is  in dynamic memory owned by Tcl and is only guaranteed to retain its
       value as long as the command is not deleted or renamed;	callers should
       copy the string if they need to keep it for a long time.

       Tcl_GetCommandFullName  produces	 the fully qualified name of a command
       from a command token.  The name, including all namespace	 prefixes,  is
       appended to the value specified by objPtr.

       Tcl_GetCommandFromObj  returns a token for the command specified by the
       name in a Tcl_Obj.  The command name is resolved relative to  the  cur‐
       rent namespace.	Returns NULL if the command is not found.

SEE ALSO
       Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)

KEYWORDS
       bind, command, create, delete, namespace, value



Tcl				      8.0	       Tcl_CreateObjCommand(3)

Tcl_Ensemble(3)		    Tcl Library Procedures	       Tcl_Ensemble(3)



______________________________________________________________________________

NAME
       Tcl_CreateEnsemble,	 Tcl_FindEnsemble,	 Tcl_GetEnsembleFlags,
       Tcl_GetEnsembleMappingDict,   Tcl_GetEnsembleNamespace,	 Tcl_GetEnsem‐
       bleParameterList, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcom‐
       mandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMapping‐
       Dict,	Tcl_SetEnsembleParameterList,	Tcl_SetEnsembleSubcommandList,
       Tcl_SetEnsembleUnknownHandler - manipulate ensemble commands

SYNOPSIS
       #include <tcl.h>

       Tcl_Command
       Tcl_CreateEnsemble(interp, name, namespacePtr, ensFlags)

       Tcl_Command
       Tcl_FindEnsemble(interp, cmdNameObj, flags)

       int
       Tcl_IsEnsemble(token)

       int
       Tcl_GetEnsembleFlags(interp, token, ensFlagsPtr)

       int
       Tcl_SetEnsembleFlags(interp, token, ensFlags)

       int
       Tcl_GetEnsembleMappingDict(interp, token, dictObjPtr)

       int
       Tcl_SetEnsembleMappingDict(interp, token, dictObj)

       int								       │
       Tcl_GetEnsembleParameterList(interp, token, listObjPtr)		       │

       int								       │
       Tcl_SetEnsembleParameterList(interp, token, listObj)		       │

       int
       Tcl_GetEnsembleSubcommandList(interp, token, listObjPtr)

       int
       Tcl_SetEnsembleSubcommandList(interp, token, listObj)

       int
       Tcl_GetEnsembleUnknownHandler(interp, token, listObjPtr)

       int
       Tcl_SetEnsembleUnknownHandler(interp, token, listObj)

       int
       Tcl_GetEnsembleNamespace(interp, token, namespacePtrPtr)

ARGUMENTS
       Tcl_Interp *interp (in/out)		     The interpreter in	 which
						     the  ensemble  is	to  be
						     created  or  found.  Also
						     where  error  result mes‐
						     sages  are	 written.  The
						     functions	 whose	 names
						     start with	 Tcl_GetEnsem‐
						     ble  may  have a NULL for
						     the interp, but all other
						     functions must not.

       const char *name (in)			     The  name of the ensemble
						     command to be created.

       Tcl_Namespace *namespacePtr (in)		     The  namespace  to	 which
						     the  ensemble  command is
						     to be bound, or NULL  for
						     the current namespace.

       int ensFlags (in)			     An OR'ed set of flag bits
						     describing the basic con‐
						     figuration	 of the ensem‐
						     ble. Currently  only  one
						     bit  has meaning, TCL_EN‐
						     SEMBLE_PREFIX,  which  is
						     present when the ensemble
						     command should also match
						     unambiguous  prefixes  of
						     subcommands.

       Tcl_Obj *cmdNameObj (in)			     A value holding the  name
						     of	 the  ensemble command
						     to look up.

       int flags (in)				     An OR'ed set of flag bits
						     controlling  the behavior
						     of Tcl_FindEnsemble. Cur‐
						     rently		  only
						     TCL_LEAVE_ERR_MSG is sup‐
						     ported.

       Tcl_Command token (in)			     A	normal	command	 token
						     that refers to an	ensem‐
						     ble command, or which you
						     wish to use  for  testing
						     as an ensemble command in
						     Tcl_IsEnsemble.

       int *ensFlagsPtr (out)			     Pointer  to  a   variable
						     into  which  to write the
						     current   ensemble	  flag
						     bits;  currently only the
						     bit   TCL_ENSEMBLE_PREFIX
						     is defined.

       Tcl_Obj *dictObj (in)			     A dictionary value to use
						     for the subcommand to im‐
						     plementation command pre‐
						     fix mapping dictionary in
						     the ensemble. May be NULL
						     if the mapping dictionary
						     is to be removed.

       Tcl_Obj **dictObjPtr (out)		     Pointer   to  a  variable
						     into which to  write  the
						     current  ensemble mapping
						     dictionary.

       Tcl_Obj *listObj (in)			     A list value to  use  for
						     the  list	of formal pre-
						     subcommand	   parameters,
						     the  defined list of sub‐
						     commands in  the  dictio‐
						     nary  or the unknown sub‐
						     command  handler  command
						     prefix.  May  be  NULL if
						     the  subcommand  list  or
						     unknown handler are to be
						     removed.

       Tcl_Obj **listObjPtr (out)		     Pointer  to  a   variable
						     into  which  to write the
						     current  list  of	formal
						     pre-subcommand    parame‐
						     ters, the defined list of
						     subcommands  or  the cur‐
						     rent unknown handler pre‐
						     fix.

       Tcl_Namespace **namespacePtrPtr (out)	     Pointer   to  a  variable
						     into which to  write  the
						     handle  of	 the namespace
						     to which the ensemble  is
						     bound.
______________________________________________________________________________

DESCRIPTION
       An  ensemble is a command, bound to some namespace, which consists of a
       collection of subcommands implemented by other Tcl commands. The	 first
       argument	 to  the  ensemble command is always interpreted as a selector
       that states what subcommand to execute.

       Ensembles are created using Tcl_CreateEnsemble, which takes four	 argu‐
       ments: the interpreter to work within, the name of the ensemble to cre‐
       ate, the namespace within the interpreter to bind the ensemble to,  and
       the  default  set  of ensemble flags. The result of the function is the
       command token for the ensemble, which may be used to further  configure
       the ensemble using the API described below in ENSEMBLE PROPERTIES.

       Given  the  name of an ensemble command, the token for that command may
       be retrieved using Tcl_FindEnsemble. If the given command name (in cmd‐
       NameObj) does not refer to an ensemble command, the result of the func‐
       tion is NULL and (if the TCL_LEAVE_ERR_MSG bit is set in flags) an  er‐
       ror message is left in the interpreter result.

       A command token may be checked to see if it refers to an ensemble using
       Tcl_IsEnsemble. This returns 1 if the token refers to an ensemble, or 0
       otherwise.

   ENSEMBLE PROPERTIES
       Every ensemble has four read-write properties and a read-only property.
       The properties are:

       flags (read-write)
	      The set of flags for the ensemble,  expressed  as	 a  bit-field.
	      Currently,  the only public flag is TCL_ENSEMBLE_PREFIX which is
	      set when unambiguous prefixes of subcommands are permitted to be
	      resolved	to implementations as well as exact matches. The flags
	      may  be  read  and  written   using   Tcl_GetEnsembleFlags   and
	      Tcl_SetEnsembleFlags  respectively.  The result of both of those
	      functions is a Tcl result code (TCL_OK, or TCL_ERROR if the  to‐
	      ken does not refer to an ensemble).

       mapping dictionary (read-write)
	      A dictionary containing a mapping from subcommand names to lists
	      of words to use as a command prefix  (replacing  the  first  two
	      words  of	 the command which are the ensemble command itself and
	      the subcommand name), or NULL  if	 every	subcommand  is	to  be
	      mapped  to the command with the same unqualified name in the en‐
	      semble's bound namespace. Defaults to  NULL.  May	 be  read  and
	      written using Tcl_GetEnsembleMappingDict and Tcl_SetEnsembleMap‐
	      pingDict respectively. The result of both of those functions  is
	      a	 Tcl  result  code (TCL_OK, or TCL_ERROR if the token does not
	      refer  to	 an  ensemble)	and  the  dictionary   obtained	  from
	      Tcl_GetEnsembleMappingDict should always be treated as immutable
	      even if it is unshared.  All command names in prefixes  set  via
	      Tcl_SetEnsembleMappingDict must be fully qualified.

       formal pre-subcommand parameter list (read-write)
	      A list of formal parameter names (the names only being used when │
	      generating error messages) that come at invocation of the ensem‐ │
	      ble  between  the	 name of the ensemble and the subcommand argu‐ │
	      ment. NULL (the default) is equivalent to the empty list. May be │
	      read   and   written   using   Tcl_GetEnsembleParameterList  and │
	      Tcl_SetEnsembleParameterList respectively. The result of both of │
	      those  functions	is  a Tcl result code (TCL_OK, or TCL_ERROR if │
	      the token does not refer to an ensemble) and the dictionary  ob‐ │
	      tained   from   Tcl_GetEnsembleParameterList  should  always  be │
	      treated as immutable even if it is unshared.

       subcommand list (read-write)
	      A list of all the subcommand names for the ensemble, or NULL  if
	      this  is	to be derived from either the keys of the mapping dic‐
	      tionary (see above) or (if that is also NULL) from  the  set  of
	      commands	exported by the bound namespace. May be read and writ‐
	      ten using Tcl_GetEnsembleSubcommandList and  Tcl_SetEnsembleSub‐
	      commandList  respectively. The result of both of those functions
	      is a Tcl result code (TCL_OK, or TCL_ERROR if the token does not
	      refer  to	 an ensemble) and the list obtained from Tcl_GetEnsem‐
	      bleSubcommandList should always be treated as immutable even  if
	      it is unshared.

       unknown subcommand handler command prefix (read-write)
	      A	 list  of words to prepend on the front of any subcommand when
	      the subcommand is unknown to the ensemble (according to the cur‐
	      rent  prefix  handling rule); see the namespace ensemble command
	      for more details. If NULL, the default  behavior	-  generate  a
	      suitable error message - will be used when an unknown subcommand
	      is encountered. May be read and written using Tcl_GetEnsembleUn‐
	      knownHandler and Tcl_SetEnsembleUnknownHandler respectively. The
	      result of both functions	is  a  Tcl  result  code  (TCL_OK,  or
	      TCL_ERROR	 if  the  token does not refer to an ensemble) and the
	      list obtained from Tcl_GetEnsembleUnknownHandler	should	always
	      be treated as immutable even if it is unshared.

       bound namespace (read-only)
	      The namespace to which the ensemble is bound; when the namespace
	      is deleted, so too will the ensemble, and this namespace is also
	      the  namespace  whose  list of exported commands is used if both
	      the mapping dictionary and the subcommand	 list  properties  are
	      NULL. May be read using Tcl_GetEnsembleNamespace which returns a
	      Tcl result code (TCL_OK, or TCL_ERROR if the token does not  re‐
	      fer to an ensemble).

SEE ALSO
       namespace(n), Tcl_DeleteCommandFromToken(3)

KEYWORDS
       command, ensemble



Tcl				      8.5		       Tcl_Ensemble(3)

Tcl_Ensemble(3)		    Tcl Library Procedures	       Tcl_Ensemble(3)



______________________________________________________________________________

NAME
       Tcl_CreateEnsemble,	 Tcl_FindEnsemble,	 Tcl_GetEnsembleFlags,
       Tcl_GetEnsembleMappingDict,   Tcl_GetEnsembleNamespace,	 Tcl_GetEnsem‐
       bleParameterList, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcom‐
       mandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMapping‐
       Dict,	Tcl_SetEnsembleParameterList,	Tcl_SetEnsembleSubcommandList,
       Tcl_SetEnsembleUnknownHandler - manipulate ensemble commands

SYNOPSIS
       #include <tcl.h>

       Tcl_Command
       Tcl_CreateEnsemble(interp, name, namespacePtr, ensFlags)

       Tcl_Command
       Tcl_FindEnsemble(interp, cmdNameObj, flags)

       int
       Tcl_IsEnsemble(token)

       int
       Tcl_GetEnsembleFlags(interp, token, ensFlagsPtr)

       int
       Tcl_SetEnsembleFlags(interp, token, ensFlags)

       int
       Tcl_GetEnsembleMappingDict(interp, token, dictObjPtr)

       int
       Tcl_SetEnsembleMappingDict(interp, token, dictObj)

       int								       │
       Tcl_GetEnsembleParameterList(interp, token, listObjPtr)		       │

       int								       │
       Tcl_SetEnsembleParameterList(interp, token, listObj)		       │

       int
       Tcl_GetEnsembleSubcommandList(interp, token, listObjPtr)

       int
       Tcl_SetEnsembleSubcommandList(interp, token, listObj)

       int
       Tcl_GetEnsembleUnknownHandler(interp, token, listObjPtr)

       int
       Tcl_SetEnsembleUnknownHandler(interp, token, listObj)

       int
       Tcl_GetEnsembleNamespace(interp, token, namespacePtrPtr)

ARGUMENTS
       Tcl_Interp *interp (in/out)		     The interpreter in	 which
						     the  ensemble  is	to  be
						     created  or  found.  Also
						     where  error  result mes‐
						     sages  are	 written.  The
						     functions	 whose	 names
						     start with	 Tcl_GetEnsem‐
						     ble  may  have a NULL for
						     the interp, but all other
						     functions must not.

       const char *name (in)			     The  name of the ensemble
						     command to be created.

       Tcl_Namespace *namespacePtr (in)		     The  namespace  to	 which
						     the  ensemble  command is
						     to be bound, or NULL  for
						     the current namespace.

       int ensFlags (in)			     An OR'ed set of flag bits
						     describing the basic con‐
						     figuration	 of the ensem‐
						     ble. Currently  only  one
						     bit  has meaning, TCL_EN‐
						     SEMBLE_PREFIX,  which  is
						     present when the ensemble
						     command should also match
						     unambiguous  prefixes  of
						     subcommands.

       Tcl_Obj *cmdNameObj (in)			     A value holding the  name
						     of	 the  ensemble command
						     to look up.

       int flags (in)				     An OR'ed set of flag bits
						     controlling  the behavior
						     of Tcl_FindEnsemble. Cur‐
						     rently		  only
						     TCL_LEAVE_ERR_MSG is sup‐
						     ported.

       Tcl_Command token (in)			     A	normal	command	 token
						     that refers to an	ensem‐
						     ble command, or which you
						     wish to use  for  testing
						     as an ensemble command in
						     Tcl_IsEnsemble.

       int *ensFlagsPtr (out)			     Pointer  to  a   variable
						     into  which  to write the
						     current   ensemble	  flag
						     bits;  currently only the
						     bit   TCL_ENSEMBLE_PREFIX
						     is defined.

       Tcl_Obj *dictObj (in)			     A dictionary value to use
						     for the subcommand to im‐
						     plementation command pre‐
						     fix mapping dictionary in
						     the ensemble. May be NULL
						     if the mapping dictionary
						     is to be removed.

       Tcl_Obj **dictObjPtr (out)		     Pointer   to  a  variable
						     into which to  write  the
						     current  ensemble mapping
						     dictionary.

       Tcl_Obj *listObj (in)			     A list value to  use  for
						     the  list	of formal pre-
						     subcommand	   parameters,
						     the  defined list of sub‐
						     commands in  the  dictio‐
						     nary  or the unknown sub‐
						     command  handler  command
						     prefix.  May  be  NULL if
						     the  subcommand  list  or
						     unknown handler are to be
						     removed.

       Tcl_Obj **listObjPtr (out)		     Pointer  to  a   variable
						     into  which  to write the
						     current  list  of	formal
						     pre-subcommand    parame‐
						     ters, the defined list of
						     subcommands  or  the cur‐
						     rent unknown handler pre‐
						     fix.

       Tcl_Namespace **namespacePtrPtr (out)	     Pointer   to  a  variable
						     into which to  write  the
						     handle  of	 the namespace
						     to which the ensemble  is
						     bound.
______________________________________________________________________________

DESCRIPTION
       An  ensemble is a command, bound to some namespace, which consists of a
       collection of subcommands implemented by other Tcl commands. The	 first
       argument	 to  the  ensemble command is always interpreted as a selector
       that states what subcommand to execute.

       Ensembles are created using Tcl_CreateEnsemble, which takes four	 argu‐
       ments: the interpreter to work within, the name of the ensemble to cre‐
       ate, the namespace within the interpreter to bind the ensemble to,  and
       the  default  set  of ensemble flags. The result of the function is the
       command token for the ensemble, which may be used to further  configure
       the ensemble using the API described below in ENSEMBLE PROPERTIES.

       Given  the  name of an ensemble command, the token for that command may
       be retrieved using Tcl_FindEnsemble. If the given command name (in cmd‐
       NameObj) does not refer to an ensemble command, the result of the func‐
       tion is NULL and (if the TCL_LEAVE_ERR_MSG bit is set in flags) an  er‐
       ror message is left in the interpreter result.

       A command token may be checked to see if it refers to an ensemble using
       Tcl_IsEnsemble. This returns 1 if the token refers to an ensemble, or 0
       otherwise.

   ENSEMBLE PROPERTIES
       Every ensemble has four read-write properties and a read-only property.
       The properties are:

       flags (read-write)
	      The set of flags for the ensemble,  expressed  as	 a  bit-field.
	      Currently,  the only public flag is TCL_ENSEMBLE_PREFIX which is
	      set when unambiguous prefixes of subcommands are permitted to be
	      resolved	to implementations as well as exact matches. The flags
	      may  be  read  and  written   using   Tcl_GetEnsembleFlags   and
	      Tcl_SetEnsembleFlags  respectively.  The result of both of those
	      functions is a Tcl result code (TCL_OK, or TCL_ERROR if the  to‐
	      ken does not refer to an ensemble).

       mapping dictionary (read-write)
	      A dictionary containing a mapping from subcommand names to lists
	      of words to use as a command prefix  (replacing  the  first  two
	      words  of	 the command which are the ensemble command itself and
	      the subcommand name), or NULL  if	 every	subcommand  is	to  be
	      mapped  to the command with the same unqualified name in the en‐
	      semble's bound namespace. Defaults to  NULL.  May	 be  read  and
	      written using Tcl_GetEnsembleMappingDict and Tcl_SetEnsembleMap‐
	      pingDict respectively. The result of both of those functions  is
	      a	 Tcl  result  code (TCL_OK, or TCL_ERROR if the token does not
	      refer  to	 an  ensemble)	and  the  dictionary   obtained	  from
	      Tcl_GetEnsembleMappingDict should always be treated as immutable
	      even if it is unshared.  All command names in prefixes  set  via
	      Tcl_SetEnsembleMappingDict must be fully qualified.

       formal pre-subcommand parameter list (read-write)
	      A list of formal parameter names (the names only being used when │
	      generating error messages) that come at invocation of the ensem‐ │
	      ble  between  the	 name of the ensemble and the subcommand argu‐ │
	      ment. NULL (the default) is equivalent to the empty list. May be │
	      read   and   written   using   Tcl_GetEnsembleParameterList  and │
	      Tcl_SetEnsembleParameterList respectively. The result of both of │
	      those  functions	is  a Tcl result code (TCL_OK, or TCL_ERROR if │
	      the token does not refer to an ensemble) and the dictionary  ob‐ │
	      tained   from   Tcl_GetEnsembleParameterList  should  always  be │
	      treated as immutable even if it is unshared.

       subcommand list (read-write)
	      A list of all the subcommand names for the ensemble, or NULL  if
	      this  is	to be derived from either the keys of the mapping dic‐
	      tionary (see above) or (if that is also NULL) from  the  set  of
	      commands	exported by the bound namespace. May be read and writ‐
	      ten using Tcl_GetEnsembleSubcommandList and  Tcl_SetEnsembleSub‐
	      commandList  respectively. The result of both of those functions
	      is a Tcl result code (TCL_OK, or TCL_ERROR if the token does not
	      refer  to	 an ensemble) and the list obtained from Tcl_GetEnsem‐
	      bleSubcommandList should always be treated as immutable even  if
	      it is unshared.

       unknown subcommand handler command prefix (read-write)
	      A	 list  of words to prepend on the front of any subcommand when
	      the subcommand is unknown to the ensemble (according to the cur‐
	      rent  prefix  handling rule); see the namespace ensemble command
	      for more details. If NULL, the default  behavior	-  generate  a
	      suitable error message - will be used when an unknown subcommand
	      is encountered. May be read and written using Tcl_GetEnsembleUn‐
	      knownHandler and Tcl_SetEnsembleUnknownHandler respectively. The
	      result of both functions	is  a  Tcl  result  code  (TCL_OK,  or
	      TCL_ERROR	 if  the  token does not refer to an ensemble) and the
	      list obtained from Tcl_GetEnsembleUnknownHandler	should	always
	      be treated as immutable even if it is unshared.

       bound namespace (read-only)
	      The namespace to which the ensemble is bound; when the namespace
	      is deleted, so too will the ensemble, and this namespace is also
	      the  namespace  whose  list of exported commands is used if both
	      the mapping dictionary and the subcommand	 list  properties  are
	      NULL. May be read using Tcl_GetEnsembleNamespace which returns a
	      Tcl result code (TCL_OK, or TCL_ERROR if the token does not  re‐
	      fer to an ensemble).

SEE ALSO
       namespace(n), Tcl_DeleteCommandFromToken(3)

KEYWORDS
       command, ensemble



Tcl				      8.5		       Tcl_Ensemble(3)

Filesystem(3)		    Tcl Library Procedures		 Filesystem(3)



______________________________________________________________________________

NAME
       Tcl_FSRegister,	 Tcl_FSUnregister,   Tcl_FSData,  Tcl_FSMountsChanged,
       Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile,  Tcl_FS‐
       CopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDi‐
       rectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile,  Tcl_FSE‐
       valFileEx,  Tcl_FSLoadFile,  Tcl_FSUnloadFile,  Tcl_FSMatchInDirectory,
       Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAt‐
       trsSet,	Tcl_FSFileAttrStrings,	Tcl_FSStat,  Tcl_FSAccess, Tcl_FSOpen‐
       FileChannel,    Tcl_FSGetCwd,	 Tcl_FSChdir,	  Tcl_FSPathSeparator,
       Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalized‐
       Path, Tcl_FSJoinToPath, Tcl_FSConvertToPathType,	 Tcl_FSGetInternalRep,
       Tcl_FSGetTranslatedPath,	  Tcl_FSGetTranslatedStringPath,  Tcl_FSNewNa‐
       tivePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_GetAccessTime‐
       FromStat,	Tcl_GetBlockSizeFromStat,	Tcl_GetBlocksFromStat,
       Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat,  Tcl_GetFSDevice‐
       FromStat,	Tcl_GetFSInodeFromStat,	       Tcl_GetGroupIdFromStat,
       Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTime‐
       FromStat,  Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, Tcl_AllocStatBuf
       - procedures to interact with any filesystem

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_FSRegister(clientData, fsPtr)

       int
       Tcl_FSUnregister(fsPtr)

       void *
       Tcl_FSData(fsPtr)

       Tcl_FSMountsChanged(fsPtr)

       const Tcl_Filesystem *
       Tcl_FSGetFileSystemForPath(pathPtr)

       Tcl_PathType
       Tcl_FSGetPathType(pathPtr)

       int
       Tcl_FSCopyFile(srcPathPtr, destPathPtr)

       int
       Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)

       int
       Tcl_FSCreateDirectory(pathPtr)

       int
       Tcl_FSDeleteFile(pathPtr)

       int
       Tcl_FSRemoveDirectory(pathPtr, recursive, errorPtr)

       int
       Tcl_FSRenameFile(srcPathPtr, destPathPtr)

       Tcl_Obj *
       Tcl_FSListVolumes(void)

       int
       Tcl_FSEvalFileEx(interp, pathPtr, encodingName)

       int
       Tcl_FSEvalFile(interp, pathPtr)

       int
       Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
		      loadHandlePtr, unloadProcPtr)

       int								       │
       Tcl_FSUnloadFile(interp, loadHandle)				       │

       int
       Tcl_FSMatchInDirectory(interp, resultPtr, pathPtr, pattern, types)

       Tcl_Obj *
       Tcl_FSLink(linkNamePtr, toPtr, linkAction)

       int
       Tcl_FSLstat(pathPtr, statPtr)

       int
       Tcl_FSUtime(pathPtr, tval)

       int
       Tcl_FSFileAttrsGet(interp, index, pathPtr, objPtrRef)

       int
       Tcl_FSFileAttrsSet(interp, index, pathPtr, objPtr)

       const char *const *
       Tcl_FSFileAttrStrings(pathPtr, objPtrRef)

       int
       Tcl_FSStat(pathPtr, statPtr)

       int
       Tcl_FSAccess(pathPtr, mode)

       Tcl_Channel
       Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)

       Tcl_Obj *
       Tcl_FSGetCwd(interp)

       int
       Tcl_FSChdir(pathPtr)

       Tcl_Obj *
       Tcl_FSPathSeparator(pathPtr)

       Tcl_Obj *
       Tcl_FSJoinPath(listObj, elements)

       Tcl_Obj *
       Tcl_FSSplitPath(pathPtr, lenPtr)

       int
       Tcl_FSEqualPaths(firstPtr, secondPtr)

       Tcl_Obj *
       Tcl_FSGetNormalizedPath(interp, pathPtr)

       Tcl_Obj *
       Tcl_FSJoinToPath(basePtr, objc, objv)

       int
       Tcl_FSConvertToPathType(interp, pathPtr)

       void *
       Tcl_FSGetInternalRep(pathPtr, fsPtr)

       Tcl_Obj *
       Tcl_FSGetTranslatedPath(interp, pathPtr)

       const char *
       Tcl_FSGetTranslatedStringPath(interp, pathPtr)

       Tcl_Obj *
       Tcl_FSNewNativePath(fsPtr, clientData)

       const void *
       Tcl_FSGetNativePath(pathPtr)

       Tcl_Obj *
       Tcl_FSFileSystemInfo(pathPtr)

       Tcl_StatBuf *
       Tcl_AllocStatBuf()

       Tcl_WideInt							       │
       Tcl_GetAccessTimeFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetBlockSizeFromStat(statPtr)				       │

       Tcl_WideUInt							       │
       Tcl_GetBlocksFromStat(statPtr)					       │

       Tcl_WideInt							       │
       Tcl_GetChangeTimeFromStat(statPtr)				       │

       int								       │
       Tcl_GetDeviceTypeFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetFSDeviceFromStat(statPtr)					       │

       unsigned								       │
       Tcl_GetFSInodeFromStat(statPtr)					       │

       int								       │
       Tcl_GetGroupIdFromStat(statPtr)					       │

       int								       │
       Tcl_GetLinkCountFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetModeFromStat(statPtr)					       │

       Tcl_WideInt							       │
       Tcl_GetModificationTimeFromStat(statPtr)				       │

       Tcl_WideUInt							       │
       Tcl_GetSizeFromStat(statPtr)					       │

       int								       │
       Tcl_GetUserIdFromStat(statPtr)					       │

ARGUMENTS
       const Tcl_Filesystem *fsPtr (in)		   Points to a structure  con‐
						   taining  the	 addresses  of
						   procedures  that   can   be
						   called to perform the vari‐
						   ous filesystem operations.

       Tcl_Obj *pathPtr (in)			   The	path  represented   by
						   this	 value is used for the
						   operation in	 question.  If
						   the	value does not already
						   have an internal path  rep‐
						   resentation,	  it  will  be
						   converted to have one.

       Tcl_Obj *srcPathPtr (in)			   As for  pathPtr,  but  used
						   for	the  source file for a
						   copy or rename operation.

       Tcl_Obj *destPathPtr (in)		   As for  pathPtr,  but  used
						   for	the  destination file‐
						   name for a copy  or	rename
						   operation.

       int recursive (in)			   Whether to remove subdirec‐
						   tories and  their  contents
						   as well.

       const char *encodingName (in)		   The	encoding  of  the data
						   stored in the file  identi‐
						   fied	 by  pathPtr and to be
						   evaluated.

       const char *pattern (in)			   Only files  or  directories
						   matching  this pattern will
						   be returned.

       Tcl_GlobTypeData *types (in)		   Only files  or  directories
						   matching  the type descrip‐
						   tions  contained  in	  this
						   structure will be returned.
						   This parameter may be NULL.

       Tcl_Interp *interp (in)			   Interpreter to  use	either
						   for results, evaluation, or
						   reporting error messages.

       void *clientData (in)			   The native  description  of
						   the path value to create.

       Tcl_Obj *firstPtr (in)			   The	first of two path val‐
						   ues to compare.  The	 value
						   may	be  converted  to path
						   type.

       Tcl_Obj *secondPtr (in)			   The second of two path val‐
						   ues	to  compare. The value
						   may be  converted  to  path
						   type.

       Tcl_Obj *listObj (in)			   The	list  of path elements
						   to operate on with  a  join
						   operation.

       int elements (in)			   The	number	of elements in
						   the listObj which should be
						   joined  together.  If nega‐
						   tive, then all elements are
						   joined.

       Tcl_Obj **errorPtr (out)			   In  the  case  of an error,
						   filled with	a  value  con‐
						   taining  the	 name  of  the
						   file which caused an	 error
						   in  the various copy/rename
						   operations.

       int index (in)				   The index of the  attribute
						   in question.

       Tcl_Obj *objPtr (in)			   The value to set in the op‐
						   eration.

       Tcl_Obj **objPtrRef (out)		   Filled with	a  value  con‐
						   taining  the	 result of the
						   operation.

       Tcl_Obj *resultPtr (out)			   Preallocated value in which
						   to store (using Tcl_ListOb‐
						   jAppendElement) the list of
						   files  or directories which
						   are successfully matched.

       int mode (in)				   Mask consisting of  one  or
						   more	 of  R_OK,  W_OK, X_OK
						   and F_OK.  R_OK,  W_OK  and
						   X_OK	   request    checking
						   whether the file exists and
						   has	 read, write and  exe‐
						   cute	 permissions,  respec‐
						   tively.  F_OK just requests
						   checking for the  existence
						   of the file.

       Tcl_StatBuf *statPtr (out)		   The structure that contains
						   the result  of  a  stat  or
						   lstat operation.

       const char *sym1 (in)			   Name of a procedure to look
						   up in the file's symbol ta‐
						   ble

       const char *sym2 (in)			   Name of a procedure to look
						   up in the file's symbol ta‐
						   ble

       Tcl_PackageInitProc **proc1Ptr (out)	   Filled  with the init func‐
						   tion for this code.

       Tcl_PackageInitProc **proc2Ptr (out)	   Filled with	the  safe-init
						   function for this code.

       void **clientDataPtr (out)		   Filled  with the clientData
						   value  to  pass   to	  this
						   code's unload function when
						   it is called.

       Tcl_LoadHandle *loadHandlePtr (out)	   Filled with an abstract to‐
						   ken representing the loaded
						   file.

       Tcl_FSUnloadFileProc **unloadProcPtr (out)  Filled with the function to
						   use to unload this piece of
						   code.

       Tcl_LoadHandle loadHandle (in)		   Handle to  the  loaded  li‐
						   brary to be unloaded.

       utimbuf *tval (in)			   The access and modification
						   times in this structure are
						   read	 and used to set those
						   values for a given file.

       const char *modeString (in)		   Specifies how the  file  is
						   to  be  accessed.  May have
						   any of the  values  allowed
						   for	the  mode  argument to
						   the Tcl open command.

       int permissions (in)			   POSIX-style	    permission
						   flags  such	as  0644. If a
						   new file is created,	 these
						   permissions	will be set on
						   the created file.

       int *lenPtr (out)			   If  non-NULL,  filled  with
						   the	number	of elements in
						   the split path.

       Tcl_Obj *basePtr (in)			   The base path on  to	 which
						   to join the given elements.
						   May be NULL.

       int objc (in)				   The number of  elements  in
						   objv.

       Tcl_Obj *const objv[] (in)		   The elements to join to the
						   given base path.

       Tcl_Obj *linkNamePtr (in)		   The name of the link to  be
						   created or read.

       Tcl_Obj *toPtr (in)			   What	   the	 link	called
						   linkNamePtr	  should    be
						   linked  to,	or NULL if the
						   symbolic link specified  by
						   linkNamePtr is to be read.

       int linkAction (in)			   OR-ed  combination of flags
						   indicating  what  kind   of
						   link	  should   be  created
						   (will be ignored  if	 toPtr
						   is NULL). Valid bits to set
						   are	       TCL_CREATE_SYM‐
						   BOLIC_LINK	and   TCL_CRE‐
						   ATE_HARD_LINK.   When  both
						   flags  are  set and the un‐
						   derlying filesystem can  do
						   either,  symbolic links are
						   preferred.
______________________________________________________________________________

DESCRIPTION
       There  are  several  reasons  for  calling  the	Tcl_FS	API  functions
       (e.g. Tcl_FSAccess  and	Tcl_FSStat)  rather  than calling system level
       functions like access and stat directly. First, they will  work	cross-
       platform,  so  an  extension which calls them should work unmodified on
       Unix and Windows. Second, the Windows implementation of some  of	 these
       functions fixes some bugs in the system level calls. Third, these func‐
       tion calls deal with any	 “Utf  to  platform-native”  path  conversions
       which  may  be  required (and may cache the results of such conversions
       for greater efficiency on subsequent calls). Fourth, and	 perhaps  most
       importantly,  all  of  these  functions are “virtual filesystem aware”.
       Any virtual filesystem  (VFS  for  short)  which	 has  been  registered
       (through	 Tcl_FSRegister)  may reroute file access to alternative media
       or access methods. This means that all of these functions  (and	there‐
       fore  the  corresponding	 file, glob, pwd, cd, open, etc. Tcl commands)
       may be operate on “files” which are not	native	files  in  the	native
       filesystem.  This  also means that any Tcl extension which accesses the
       filesystem (FS for short) through this API  is  automatically  “virtual
       filesystem  aware”.   Of	 course,  if  an extension accesses the native
       filesystem directly (through platform-specific APIs, for example), then
       Tcl cannot intercept such calls.

       If appropriate VFSes have been registered, the “files” may, to give two
       examples, be remote (e.g. situated on a remote ftp server) or  archived
       (e.g. lying inside a .zip archive). Such registered filesystems provide
       a lookup table of functions to implement all or some of the functional‐
       ity listed here. Finally, the Tcl_FSStat and Tcl_FSLstat calls abstract
       away from what the “struct stat” buffer is actually declared to be, al‐
       lowing  the same code to be used both on systems with and systems with‐
       out support for files larger than 2GB in size.

       The Tcl_FS API is Tcl_Obj-ified and may cache internal  representations
       and  other  path-related	 strings (e.g. the current working directory).
       One side-effect of this is that one must not pass in values with a ref‐
       erence count of zero to any of these functions. If such calls were han‐
       dled, they might result in memory leaks (under some circumstances,  the
       filesystem  code may wish to retain a reference to the passed in value,
       and so one must not assume that after any of these  calls  return,  the
       value  still  has  a  reference count of zero - it may have been incre‐
       mented) or in a direct segmentation fault (or other memory  access  er‐
       ror)  due  to  the value being freed part way through the complex value
       manipulation required to ensure that the path is fully  normalized  and
       absolute	 for  filesystem  determination. The practical lesson to learn
       from this is that

	      Tcl_Obj *path = Tcl_NewStringObj(...);
	      Tcl_FSWhatever(path);
	      Tcl_DecrRefCount(path);

       is wrong, and may cause memory errors. The path must have its reference
       count  incremented  before  passing it in, or decrementing it. For this
       reason, values with a reference count of zero are considered not to  be
       valid  filesystem paths and calling any Tcl_FS API function with such a
       value will result in no action being taken.

   FS API FUNCTIONS
       Tcl_FSCopyFile attempts to copy the file given  by  srcPathPtr  to  the
       path  name given by destPathPtr. If the two paths given lie in the same
       filesystem (according to Tcl_FSGetFileSystemForPath) then that filesys‐
       tem's  “copy  file”  function is called (if it is non-NULL).  Otherwise
       the function returns -1 and sets the errno global  C  variable  to  the
       “EXDEV” POSIX error code (which signifies a “cross-domain link”).

       Tcl_FSCopyDirectory  attempts to copy the directory given by srcPathPtr
       to the path name given by destPathPtr. If the two paths	given  lie  in
       the same filesystem (according to Tcl_FSGetFileSystemForPath) then that
       filesystem's “copy file” function is called (if it is non-NULL).	  Oth‐
       erwise  the function returns -1 and sets the errno global C variable to
       the “EXDEV” POSIX error code (which signifies a “cross-domain link”).

       Tcl_FSCreateDirectory attempts to create the directory given by pathPtr
       by calling the owning filesystem's “create directory” function.

       Tcl_FSDeleteFile	 attempts to delete the file given by pathPtr by call‐
       ing the owning filesystem's “delete file” function.

       Tcl_FSRemoveDirectory attempts to remove the directory given by pathPtr
       by calling the owning filesystem's “remove directory” function.

       Tcl_FSRenameFile attempts to rename the file or directory given by src‐
       PathPtr to the path name given by destPathPtr. If the two  paths	 given
       lie  in	the  same filesystem (according to Tcl_FSGetFileSystemForPath)
       then that filesystem's “rename file” function is called (if it is  non-
       NULL).  Otherwise  the  function returns -1 and sets the errno global C
       variable to the “EXDEV” POSIX error code (which signifies a  “cross-do‐
       main link”).

       Tcl_FSListVolumes calls each filesystem which has a non-NULL “list vol‐
       umes” function and asks them to return their list of root  volumes.  It
       accumulates the return values in a list which is returned to the caller
       (with a reference count of 0).

       Tcl_FSEvalFileEx reads the file given by	 pathPtr  using	 the  encoding
       identified  by encodingName and evaluates its contents as a Tcl script.
       It returns the same information as Tcl_EvalObjEx.  If  encodingName  is
       NULL,  the  system  encoding is used for reading the file contents.  If
       the file could not be read then a Tcl error is returned to describe why
       the  file  could not be read.  The eofchar for files is “\x1A” (^Z) for
       all platforms.  If you require a “^Z” in code  for  string  comparison,
       you  can use “\x1A”, which will be safely substituted by the Tcl inter‐
       preter into “^Z”.  Tcl_FSEvalFile is a simpler version  of  Tcl_FSEval‐
       FileEx that always uses the system encoding when reading the file.

       Tcl_FSLoadFile dynamically loads a binary code file into memory and re‐
       turns the addresses of two procedures within that file, if they are de‐
       fined. The appropriate function for the filesystem to which pathPtr be‐
       longs will be called. If that filesystem does not implement this	 func‐
       tion  (most  virtual filesystems will not, because of OS limitations in
       dynamically loading binary code), Tcl will attempt to copy the file  to
       a  temporary  directory and load that temporary file.  Tcl_FSUnloadFile │
       reverses the operation, asking for the library indicated by  the	 load‐ │
       Handle  to  be removed from the process. Note that, unlike with the un‐ │
       load command, this does not give the library any opportunity  to	 clean │
       up.

       Both  the  above functions return a standard Tcl completion code. If an
       error occurs, an error message is left in the interp's result.

       The token provided via the variable indicated by loadHandlePtr  may  be │
       used with Tcl_FindSymbol.

       Tcl_FSMatchInDirectory  is used by the globbing code to search a direc‐
       tory for all files which match a given pattern. The  appropriate	 func‐
       tion for the filesystem to which pathPtr belongs will be called.

       The  return  value is a standard Tcl result indicating whether an error
       occurred in globbing. Error messages are placed in interp  (unless  in‐
       terp is NULL, which is allowed), but good results are placed in the re‐
       sultPtr given.

       Note that the glob code implements recursive  patterns  internally,  so
       this  function  will  only ever be passed simple patterns, which can be
       matched using the logic of string match. To handle recursion, Tcl  will
       call  this  function  frequently	 asking only for directories to be re‐
       turned. A special case of being called with a  NULL  pattern  indicates
       that the path needs to be checked only for the correct type.

       Tcl_FSLink  replaces the library version of readlink, and extends it to
       support the  creation  of  links.  The  appropriate  function  for  the
       filesystem to which linkNamePtr belongs will be called.

       If  the toPtr is NULL, a “read link” action is performed. The result is
       a Tcl_Obj specifying  the  contents  of	the  symbolic  link  given  by
       linkNamePtr, or NULL if the link could not be read. The result is owned
       by the caller, which should call Tcl_DecrRefCount when the result is no
       longer  needed.	If  the toPtr is not NULL, Tcl should create a link of
       one of the types passed in in the linkAction flag.   This  flag	is  an
       OR'ed combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CREATE_HARD_LINK.
       Where a choice exists (i.e. more than one flag is passed in),  the  Tcl
       convention  is  to  prefer  symbolic links. When a link is successfully
       created, the return value should be toPtr (which is  therefore  already
       owned by the caller). If unsuccessful, NULL is returned.

       Tcl_FSLstat  fills  the	Tcl_StatBuf structure statPtr with information
       about the specified file. You do not need any access rights to the file
       to  get	this information but you need search rights to all directories
       named in the path leading to the file. The  Tcl_StatBuf	structure  in‐
       cludes  info  regarding	device, inode (always 0 on Windows), privilege
       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
       id  (always 0 on Windows), rdev (same as device on Windows), size, last
       access time, last modification time, and	 last  metadata	 change	 time.
       See PORTABLE STAT RESULT API for a description of how to write portable
       code to allocate and access the Tcl_StatBuf structure.

       If path exists, Tcl_FSLstat returns 0 and the stat structure is	filled
       with data. Otherwise, -1 is returned, and no stat info is given.

       Tcl_FSUtime replaces the library version of utime.

       This  returns 0 on success and -1 on error (as per the utime documenta‐
       tion). If successful, the function will update the “atime” and  “mtime”
       values of the file given.

       Tcl_FSFileAttrsGet  implements  read  access  for the hookable file at‐
       tributes subcommand. The appropriate function  for  the	filesystem  to
       which pathPtr belongs will be called.

       If  the	result	is TCL_OK, then a value was placed in objPtrRef, which
       will only be temporarily valid (unless Tcl_IncrRefCount is called).

       Tcl_FSFileAttrsSet implements write access for the  hookable  file  at‐
       tributes	 subcommand.  The  appropriate	function for the filesystem to
       which pathPtr belongs will be called.

       Tcl_FSFileAttrStrings implements part of the hookable  file  attributes
       subcommand.  The appropriate function for the filesystem to which path‐
       Ptr belongs will be called.

       The called procedure may either return an array of strings, or may  in‐
       stead  return  NULL  and place a Tcl list into the given objPtrRef. Tcl
       will take that list and first increment its reference count before  us‐
       ing  it.	  On  completion of that use, Tcl will decrement its reference
       count. Hence if the list should be disposed of by  Tcl  when  done,  it
       should  have  a	reference count of zero, and if the list should not be
       disposed of, the filesystem should ensure it retains a reference	 count
       to the value.

       Tcl_FSAccess checks whether the process would be allowed to read, write
       or test for existence of the file (or other  filesystem	object)	 whose
       name  is pathname. If pathname is a symbolic link on Unix, then permis‐
       sions of the file referred by this symbolic link are tested.

       On success (all requested permissions granted), zero  is	 returned.  On
       error  (at least one bit in mode asked for a permission that is denied,
       or some other error occurred), -1 is returned.

       Tcl_FSStat fills the Tcl_StatBuf	 structure  statPtr  with  information
       about the specified file. You do not need any access rights to the file
       to get this information but you need search rights to  all  directories
       named  in  the  path leading to the file. The Tcl_StatBuf structure in‐
       cludes info regarding device, inode (always 0  on  Windows),  privilege
       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
       id (always 0 on Windows), rdev (same as device on Windows), size,  last
       access  time,  last  modification  time, and last metadata change time.
       See PORTABLE STAT RESULT API for a description of how to write portable
       code to allocate and access the Tcl_StatBuf structure.

       If  path	 exists, Tcl_FSStat returns 0 and the stat structure is filled
       with data. Otherwise, -1 is returned, and no stat info is given.

       Tcl_FSOpenFileChannel opens a file specified by pathPtr and  returns  a
       channel	handle	that  can  be  used to perform input and output on the
       file. This API is modeled after the fopen procedure of the  Unix	 stan‐
       dard  I/O  library.  The syntax and meaning of all arguments is similar
       to those given in the Tcl open command when opening a file.  If an  er‐
       ror  occurs  while  opening  the channel, Tcl_FSOpenFileChannel returns
       NULL and records	 a  POSIX  error  code	that  can  be  retrieved  with
       Tcl_GetErrno.   In addition, if interp is non-NULL, Tcl_FSOpenFileChan‐
       nel leaves an error message in interp's result after any error.

       The newly created channel is not	 registered  in	 the  supplied	inter‐
       preter;	to  register it, use Tcl_RegisterChannel.  If one of the stan‐
       dard channels, stdin, stdout or stderr was previously closed,  the  act
       of  creating  the  new channel also assigns it as a replacement for the
       standard channel.

       Tcl_FSGetCwd replaces the library version of getcwd.

       It returns the Tcl library's current working  directory.	 This  may  be
       different  to  the  native  platform's working directory, which happens
       when the current working directory is not in the native filesystem.

       The result is a pointer to a Tcl_Obj specifying the current  directory,
       or  NULL	 if  the current directory could not be determined. If NULL is
       returned, an error message is left in the interp's result.

       The result already has its reference count incremented for the  caller.
       When  it	 is  no	 longer	 needed, that reference count should be decre‐
       mented. This is needed for thread-safety purposes,  to  allow  multiple
       threads	to  access  this and related functions, while ensuring the re‐
       sults are always valid.

       Tcl_FSChdir replaces the library version of chdir. The path is  normal‐
       ized  and  then	passed	to  the	 filesystem  which  claims it. If that
       filesystem does not implement this function, Tcl	 will  fallback	 to  a
       combination  of	stat  and access to check whether the directory exists
       and has appropriate permissions.

       For results, see chdir documentation. If successful, we keep  a	record
       of  the	successful  path in cwdPathPtr for subsequent calls to Tcl_FS‐
       GetCwd.

       Tcl_FSPathSeparator returns the separator character to be used for most
       specific	 element  of the path specified by pathPtr (i.e. the last part
       of the path).

       The separator is returned as a Tcl_Obj containing a string of length 1.
       If the path is invalid, NULL is returned.

       Tcl_FSJoinPath  takes  the  given  Tcl_Obj,  which must be a valid list
       (which is allowed to have a reference count of zero), and  returns  the
       path  value  given  by considering the first elements elements as valid
       path segments (each path segment may be a complete path, a partial path
       or  just a single possible directory or file name). If any path segment
       is actually an absolute path, then all prior  path  segments  are  dis‐
       carded.	If elements is less than 0, we use the entire list.

       It  is  possible	 that the returned value is actually an element of the
       given list, so the caller should be careful to increment the  reference
       count of the result before freeing the list.

       The  returned  value,  typically with a reference count of zero (but it
       could be shared under some conditions), contains the joined  path.  The
       caller must add a reference count to the value before using it. In par‐
       ticular, the returned value could be an element of the given  list,  so
       freeing the list might free the value prematurely if no reference count
       has been taken.	If the number of elements is zero, then	 the  returned
       value will be an empty-string Tcl_Obj.

       Tcl_FSSplitPath	takes the given Tcl_Obj, which should be a valid path,
       and returns a Tcl list value containing each segment of that path as an
       element.	  It  returns  a list value with a reference count of zero. If
       the passed in lenPtr is non-NULL, the variable it points to will be up‐
       dated to contain the number of elements in the returned list.

       Tcl_FSEqualPaths	 tests	whether the two paths given represent the same
       filesystem object.  It returns 1 if the paths are equal, and 0 if  they
       are different. If either path is NULL, 0 is always returned.

       Tcl_FSGetNormalizedPath	attempts  to  extract from the given Tcl_Obj a
       unique normalized path representation, whose string value can  be  used
       as a unique identifier for the file.

       It returns the normalized path value, owned by Tcl, or NULL if the path
       was invalid or could otherwise not be successfully converted.   Extrac‐
       tion  of	 absolute,  normalized	paths  is  very efficient (because the
       filesystem operates on these representations internally), although  the
       result  when the filesystem contains numerous symbolic links may not be
       the most user-friendly version of a path. The return value is owned  by
       Tcl and has a lifetime equivalent to that of the pathPtr passed in (un‐
       less that is a relative path, in which case the normalized  path	 value
       may  be	freed any time the cwd changes) - the caller can of course in‐
       crement the reference count if it wishes to maintain a copy for longer.

       Tcl_FSJoinToPath takes the given value, which should usually be a valid
       path or NULL, and joins onto it the array of paths segments given.

       Returns	a  value, typically with reference count of zero (but it could
       be shared under some  conditions),  containing  the  joined  path.  The
       caller  must add a reference count to the value before using it. If any
       of the values passed into this function (pathPtr or path elements) have
       a  reference  count  of zero, they will be freed when this function re‐
       turns.

       Tcl_FSConvertToPathType tries to convert the given Tcl_Obj to  a	 valid
       Tcl path type, taking account of the fact that the cwd may have changed
       even if this value is already supposedly	 of  the  correct  type.   The
       filename may begin with “~” (to indicate current user's home directory)
       or “~<user>” (to indicate any user's home directory).

       If the conversion succeeds (i.e. the value is a valid path  in  one  of
       the  current filesystems), then TCL_OK is returned. Otherwise TCL_ERROR
       is returned, and an error message may be left in the interpreter.

       Tcl_FSGetInternalRep extracts the internal representation  of  a	 given
       path  value,  in	 the  given filesystem. If the path value belongs to a
       different filesystem, we return NULL. If the internal representation is
       currently  NULL, we attempt to generate it, by calling the filesystem's
       Tcl_FSCreateInternalRepProc.

       Returns NULL or a valid internal	 path  representation.	This  internal
       representation  is cached, so that repeated calls to this function will
       not require additional conversions.

       Tcl_FSGetTranslatedPath attempts to extract the	translated  path  from
       the given Tcl_Obj.

       If  the	translation succeeds (i.e. the value is a valid path), then it
       is returned. Otherwise NULL will be returned, and an error message  may
       be  left	 in the interpreter. A “translated” path is one which contains
       no “~” or “~user” sequences (these have been expanded to their  current
       representation  in  the filesystem). The value returned is owned by the
       caller, which must store it or call Tcl_DecrRefCount to	ensure	memory
       is  freed.  This function is of little practical use, and Tcl_FSGetNor‐
       malizedPath or Tcl_FSGetNativePath are usually better functions to  use
       for most purposes.

       Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
       but returns a character string or NULL.	The string returned is dynami‐
       cally  allocated	 and  owned by the caller, which must store it or call
       ckfree to ensure it is freed. Again, Tcl_FSGetNormalizedPath or Tcl_FS‐
       GetNativePath are usually better functions to use for most purposes.

       Tcl_FSNewNativePath  performs  something	 like the reverse of the usual
       obj->path->nativerep conversions. If some code retrieves a path in  na‐
       tive form (from, e.g. readlink or a native dialog), and that path is to
       be used at the Tcl level, then calling this function  is	 an  efficient
       way of creating the appropriate path value type.

       The  resulting  value is a pure “path” value, which will only receive a
       UTF-8 string representation if that is required by some Tcl code.

       Tcl_FSGetNativePath is for use by the Win/Unix native  filesystems,  so
       that  they can easily retrieve the native (char* or TCHAR*) representa‐
       tion of a path. This function is a convenience wrapper  around  Tcl_FS‐
       GetInternalRep.	It  may be desirable in the future to have non-string-
       based native representations (for example, on macOS,  a	representation
       using  a fileSpec of FSRef structure would probably be more efficient).
       On Windows a full Unicode representation would allow for paths  of  un‐
       limited	length.	 Currently  the	 representation	 is simply a character
       string which may contain either the relative path or a complete,	 abso‐
       lute normalized path in the native encoding (complex conditions dictate
       which of these will be provided, so neither can be relied upon,	unless
       the path is known to be absolute). If you need a native path which must
       be absolute, then you should ask for the native version of a normalized
       path.  If for some reason a non-absolute, non-normalized version of the
       path is needed, that must be constructed separately (e.g. using Tcl_FS‐
       GetTranslatedPath).

       The  native  representation  is	cached	so that repeated calls to this
       function will not require additional conversions. The return  value  is
       owned  by  Tcl  and  has	 a  lifetime equivalent to that of the pathPtr
       passed in (unless that is a relative path, in  which  case  the	native
       representation may be freed any time the cwd changes).

       Tcl_FSFileSystemInfo  returns a list of two elements. The first element
       is the name  of	the  filesystem	 (e.g.	 “native”,  “vfs”,  “zip”,  or
       “prowrap”, perhaps), and the second is the particular type of the given
       path within that filesystem (which is filesystem dependent). The second
       element may be empty if the filesystem does not provide a further cate‐
       gorization of files.

       A valid list value is returned, unless the path	value  is  not	recog‐
       nized, when NULL will be returned.

       Tcl_FSGetFileSystemForPath  returns  a  pointer	to  the Tcl_Filesystem
       which accepts this path as valid.

       If no filesystem will accept the path, NULL is returned.

       Tcl_FSGetPathType determines whether the given path is relative to  the
       current directory, relative to the current volume, or absolute.

       It    returns   one   of	  TCL_PATH_ABSOLUTE,   TCL_PATH_RELATIVE,   or
       TCL_PATH_VOLUME_RELATIVE

   PORTABLE STAT RESULT API
       Tcl_AllocStatBuf allocates a Tcl_StatBuf on the system heap (which  may
       be  deallocated	by  being passed to ckfree). This allows extensions to
       invoke Tcl_FSStat and Tcl_FSLstat without being dependent on  the  size
       of the buffer. That in turn depends on the flags used to build Tcl.

       The  portable  fields  of a Tcl_StatBuf may be read using the following │
       functions, each of which returns the value of the  corresponding	 field │
       listed  in  the	table  below. Note that on some platforms there may be │
       other fields in the Tcl_StatBuf as it is an alias for a suitable system │
       structure, but only the portable ones are made available here. See your │
       system documentation for a full description of these fields.	       │

	      Access Function			 Field			       │
	       Tcl_GetFSDeviceFromStat		  st_dev		       │
	       Tcl_GetFSInodeFromStat		  st_ino		       │
	       Tcl_GetModeFromStat		  st_mode		       │
	       Tcl_GetLinkCountFromStat		  st_nlink		       │
	       Tcl_GetUserIdFromStat		  st_uid		       │
	       Tcl_GetGroupIdFromStat		  st_gid		       │
	       Tcl_GetDeviceTypeFromStat	  st_rdev		       │
	       Tcl_GetAccessTimeFromStat	  st_atime		       │
	       Tcl_GetModificationTimeFromStat	  st_mtime		       │
	       Tcl_GetChangeTimeFromStat	  st_ctime		       │
	       Tcl_GetSizeFromStat		  st_size		       │
	       Tcl_GetBlocksFromStat		  st_blocks		       │
	       Tcl_GetBlockSizeFromStat		  st_blksize		       │


THE VIRTUAL FILESYSTEM API
       A filesystem provides a Tcl_Filesystem structure that contains pointers
       to  functions  that  implement  the various operations on a filesystem;
       these operations are invoked as needed by the generic layer, which gen‐
       erally occurs through the functions listed above.

       The Tcl_Filesystem structures are manipulated using the following meth‐
       ods.

       Tcl_FSRegister takes a pointer to a filesystem  structure  and  an  op‐
       tional  piece  of  data	to associated with that filesystem. On calling
       this function, Tcl will attach the filesystem  to  the  list  of	 known
       filesystems,  and it will become fully functional immediately. Tcl does
       not check if the same filesystem is registered multiple times  (and  in
       general that is not a good thing to do). TCL_OK will be returned.

       Tcl_FSUnregister	 removes  the given filesystem structure from the list
       of known filesystems, if it  is	known,	and  returns  TCL_OK.  If  the
       filesystem is not currently registered, TCL_ERROR is returned.

       Tcl_FSData  will	 return	 the  clientData  associated  with  the	 given
       filesystem, if that filesystem is registered. Otherwise it will	return
       NULL.

       Tcl_FSMountsChanged  is	used  to inform the Tcl's core that the set of
       mount  points  for  the	given  (already	 registered)  filesystem  have
       changed,	 and  that cached file representations may therefore no longer
       be correct.

   THE TCL_FILESYSTEM STRUCTURE
       The Tcl_Filesystem structure contains the following fields:

	      typedef struct Tcl_Filesystem {
		  const char *typeName;
		  int structureLength;
		  Tcl_FSVersion version;
		  Tcl_FSPathInFilesystemProc *pathInFilesystemProc;
		  Tcl_FSDupInternalRepProc *dupInternalRepProc;
		  Tcl_FSFreeInternalRepProc *freeInternalRepProc;
		  Tcl_FSInternalToNormalizedProc *internalToNormalizedProc;
		  Tcl_FSCreateInternalRepProc *createInternalRepProc;
		  Tcl_FSNormalizePathProc *normalizePathProc;
		  Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc;
		  Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc;
		  Tcl_FSStatProc *statProc;
		  Tcl_FSAccessProc *accessProc;
		  Tcl_FSOpenFileChannelProc *openFileChannelProc;
		  Tcl_FSMatchInDirectoryProc *matchInDirectoryProc;
		  Tcl_FSUtimeProc *utimeProc;
		  Tcl_FSLinkProc *linkProc;
		  Tcl_FSListVolumesProc *listVolumesProc;
		  Tcl_FSFileAttrStringsProc *fileAttrStringsProc;
		  Tcl_FSFileAttrsGetProc *fileAttrsGetProc;
		  Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
		  Tcl_FSCreateDirectoryProc *createDirectoryProc;
		  Tcl_FSRemoveDirectoryProc *removeDirectoryProc;
		  Tcl_FSDeleteFileProc *deleteFileProc;
		  Tcl_FSCopyFileProc *copyFileProc;
		  Tcl_FSRenameFileProc *renameFileProc;
		  Tcl_FSCopyDirectoryProc *copyDirectoryProc;
		  Tcl_FSLstatProc *lstatProc;
		  Tcl_FSLoadFileProc *loadFileProc;
		  Tcl_FSGetCwdProc *getCwdProc;
		  Tcl_FSChdirProc *chdirProc;
	      } Tcl_Filesystem;

       Except for the first three fields in this structure which contain  sim‐
       ple data elements, all entries contain addresses of functions called by
       the generic filesystem layer to perform the complete range of  filesys‐
       tem related actions.

       The  many  functions in this structure are broken down into three cate‐
       gories: infrastructure functions (almost all of which  must  be	imple‐
       mented), operational functions (which must be implemented if a complete
       filesystem is provided), and efficiency functions (which need  only  be
       implemented  if	they can be done so efficiently, or if they have side-
       effects which are required by the filesystem; Tcl  has  less  efficient
       emulations  it  can fall back on). It is important to note that, in the
       current version of Tcl, most of these fallbacks are only used to handle
       commands initiated in Tcl, not in C. What this means is, that if a file
       rename command is issued in Tcl, and the relevant filesystem(s) do  not
       implement  their Tcl_FSRenameFileProc, Tcl's core will instead fallback
       on a combination of other filesystem functions (it will use Tcl_FSCopy‐
       FileProc followed by Tcl_FSDeleteFileProc, and if Tcl_FSCopyFileProc is
       not implemented there is a further fallback). However, if  a  Tcl_FSRe‐
       nameFileProc command is issued at the C level, no such fallbacks occur.
       This is true except for the last four entries in the  filesystem	 table
       (lstat, load, getcwd and chdir) for which fallbacks do in fact occur at
       the C level.

       Any functions which take path names in Tcl_Obj form take those names in
       UTF-8  form.  The  filesystem infrastructure API is designed to support
       efficient, cached conversion of these UTF-8 paths to other native  rep‐
       resentations.

   EXAMPLE FILESYSTEM DEFINITION
       Here  is	 the filesystem lookup table used by the “vfs” extension which
       allows filesystem actions to be implemented in Tcl.

	      static Tcl_Filesystem vfsFilesystem = {
		  "tclvfs",
		  sizeof(Tcl_Filesystem),
		  TCL_FILESYSTEM_VERSION_1,
		  &VfsPathInFilesystem,
		  &VfsDupInternalRep,
		  &VfsFreeInternalRep,
		  /* No internal to normalized, since we don't create
		   * any pure 'internal' Tcl_Obj path representations */
		  NULL,
		  /* No create native rep function, since we don't use
		   * it and don't choose to support uses of
		   * Tcl_FSNewNativePath */
		  NULL,
		  /* Normalize path isn't needed - we assume paths only
		   * have one representation */
		  NULL,
		  &VfsFilesystemPathType,
		  &VfsFilesystemSeparator,
		  &VfsStat,
		  &VfsAccess,
		  &VfsOpenFileChannel,
		  &VfsMatchInDirectory,
		  &VfsUtime,
		  /* We choose not to support symbolic links inside our
		   * VFS's */
		  NULL,
		  &VfsListVolumes,
		  &VfsFileAttrStrings,
		  &VfsFileAttrsGet,
		  &VfsFileAttrsSet,
		  &VfsCreateDirectory,
		  &VfsRemoveDirectory,
		  &VfsDeleteFile,
		  /* No copy file; use the core fallback mechanism */
		  NULL,
		  /* No rename file; use the core fallback mechanism */
		  NULL,
		  /* No copy directory; use the core fallback mechanism */
		  NULL,
		  /* Core will use stat for lstat */
		  NULL,
		  /* No load; use the core fallback mechanism */
		  NULL,
		  /* We don't need a getcwd or chdir; the core's own
		   * internal value is suitable */
		  NULL,
		  NULL
	      };

FILESYSTEM INFRASTRUCTURE
       These fields contain basic information about the	 filesystem  structure
       and  addresses  of  functions  which are used to associate a particular
       filesystem with a file path, and deal with  the	internal  handling  of
       path  representations, for example copying and freeing such representa‐
       tions.

   TYPENAME
       The typeName field contains a null-terminated  string  that  identifies
       the type of the filesystem implemented, e.g.  “native”, “zip” or “vfs”.

   STRUCTURE LENGTH
       The    structureLength	 field	  is	generally    implemented    as
       sizeof(Tcl_Filesystem), and is there to allow easier  binary  backwards
       compatibility  if the size of the structure changes in a future Tcl re‐
       lease.

   VERSION
       The version field should be set to TCL_FILESYSTEM_VERSION_1.

   PATHINFILESYSTEMPROC
       The pathInFilesystemProc field contains the address of a function which
       is  called  to  determine  whether  a  given path value belongs to this
       filesystem or not. Tcl will only call the rest of the filesystem	 func‐
       tions  with a path for which this function has returned TCL_OK.	If the
       path does not belong, -1 should be returned (the behavior  of  Tcl  for
       any other return value is not defined). If TCL_OK is returned, then the
       optional clientDataPtr output parameter can be used to return an inter‐
       nal  (filesystem	 specific)  representation  of the path, which will be
       cached inside the path value, and may be retrieved efficiently  by  the
       other filesystem functions. Tcl will simultaneously cache the fact that
       this path belongs to this filesystem. Such caches are invalidated  when
       filesystem  structures are added or removed from Tcl's internal list of
       known filesystems.

	      typedef int Tcl_FSPathInFilesystemProc(
		      Tcl_Obj *pathPtr,
		      ClientData *clientDataPtr);

   DUPINTERNALREPPROC
       This function makes a copy of a path's internal representation, and  is
       called when Tcl needs to duplicate a path value. If NULL, Tcl will sim‐
       ply not copy the internal representation, which may then need to be re‐
       generated later.

	      typedef ClientData Tcl_FSDupInternalRepProc(
		      ClientData clientData);

   FREEINTERNALREPPROC
       Free  the internal representation. This must be implemented if internal
       representations need freeing (i.e. if some memory is allocated when  an
       internal representation is generated), but may otherwise be NULL.

	      typedef void Tcl_FSFreeInternalRepProc(
		      ClientData clientData);

   INTERNALTONORMALIZEDPROC
       Function	 to convert internal representation to a normalized path. Only
       required if the filesystem creates pure path values with no string/path
       representation.	The return value is a Tcl value whose string represen‐
       tation is the normalized path.

	      typedef Tcl_Obj *Tcl_FSInternalToNormalizedProc(
		      ClientData clientData);

   CREATEINTERNALREPPROC
       Function to take a path value, and calculate an internal representation
       for  it, and store that native representation in the value. May be NULL
       if paths have no	 internal  representation,  or	if  the	 Tcl_FSPathIn‐
       FilesystemProc for this filesystem always immediately creates an inter‐
       nal representation for paths it accepts.

	      typedef ClientData Tcl_FSCreateInternalRepProc(
		      Tcl_Obj *pathPtr);

   NORMALIZEPATHPROC
       Function to normalize a path. Should be implemented for all filesystems
       which can have multiple string representations for the same path value.
       In Tcl, every “path” must have a single unique “normalized” string rep‐
       resentation.  Depending	on  the filesystem, there may be more than one
       unnormalized string representation which refers to  that	 path  (e.g. a
       relative	 path,	a path with different character case if the filesystem
       is case insensitive, a path contain a reference	to  a  home  directory
       such  as	 “~”, a path containing symbolic links, etc). If the very last
       component in the path is a symbolic link, it should  not	 be  converted
       into  the  value	 it points to (but its case or other aspects should be
       made unique). All other path components should be converted  from  sym‐
       bolic  links. This one exception is required to agree with Tcl's seman‐
       tics with file delete, file rename, file	 copy  operating  on  symbolic
       links.	This  function may be called with nextCheckpoint either at the
       beginning of the path (i.e. zero), at the end of the path,  or  at  any
       intermediate  file  separator  in  the path. It will never point to any
       other arbitrary position in the path. In the last of  the  three	 valid
       cases,  the implementation can assume that the path up to and including
       the file separator is known and normalized.

	      typedef int Tcl_FSNormalizePathProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      int nextCheckpoint);

FILESYSTEM OPERATIONS
       The fields in this section of the structure contain addresses of	 func‐
       tions  which are called to carry out the basic filesystem operations. A
       filesystem which expects to be used with the complete standard Tcl com‐
       mand  set  must	implement all of these. If some of them are not imple‐
       mented, then certain Tcl commands may  fail  when  operating  on	 paths
       within  that  filesystem. However, in some instances this may be desir‐
       able (for example, a read-only filesystem should not implement the last
       four  functions, and a filesystem which does not support symbolic links
       need not implement the readlink function, etc.  The  Tcl	 core  expects
       filesystems to behave in this way).

   FILESYSTEMPATHTYPEPROC
       Function	 to  determine	the  type of a path in this filesystem. May be
       NULL, in which case no type information will be available to  users  of
       the filesystem. The “type” is used only for informational purposes, and
       should be returned as the string representation of the Tcl_Obj which is
       returned.  A typical return value might be “networked”, “zip” or “ftp”.
       The Tcl_Obj result is owned by the filesystem and so Tcl will increment
       the reference count of that value if it wishes to retain a reference to
       it.

	      typedef Tcl_Obj *Tcl_FSFilesystemPathTypeProc(
		      Tcl_Obj *pathPtr);

   FILESYSTEMSEPARATORPROC
       Function to return the  separator  character(s)	for  this  filesystem.
       This need only be implemented if the filesystem wishes to use a differ‐
       ent separator than the standard string “/”.  Amongst other uses, it  is
       returned	 by  the  file separator command. The return value should be a
       value with reference count of zero.

	      typedef Tcl_Obj *Tcl_FSFilesystemSeparatorProc(
		      Tcl_Obj *pathPtr);

   STATPROC
       Function to process a Tcl_FSStat call. Must be implemented for any rea‐
       sonable filesystem, since many Tcl level commands depend crucially upon
       it (e.g. file atime, file isdirectory, file size, glob).

	      typedef int Tcl_FSStatProc(
		      Tcl_Obj *pathPtr,
		      Tcl_StatBuf *statPtr);

       The Tcl_FSStatProc fills the stat structure  statPtr  with  information
       about the specified file. You do not need any access rights to the file
       to get this information but you need search rights to  all  directories
       named in the path leading to the file. The stat structure includes info
       regarding device, inode (always 0 on Windows),  privilege  mode,	 nlink
       (always	1 on Windows), user id (always 0 on Windows), group id (always
       0 on Windows), rdev (same as device  on	Windows),  size,  last	access
       time, last modification time, and last metadata change time.

       If the file represented by pathPtr exists, the Tcl_FSStatProc returns 0
       and the stat structure is filled with data. Otherwise, -1 is  returned,
       and no stat info is given.

   ACCESSPROC
       Function	 to  process  a Tcl_FSAccess call. Must be implemented for any
       reasonable filesystem, since many Tcl level commands  depend  crucially
       upon it (e.g. file exists, file readable).

	      typedef int Tcl_FSAccessProc(
		      Tcl_Obj *pathPtr,
		      int mode);

       The  Tcl_FSAccessProc  checks  whether  the process would be allowed to
       read, write or test for existence of the file (or other filesystem  ob‐
       ject)  whose  name  is in pathPtr. If the pathname refers to a symbolic
       link, then the permissions of the file referred by this	symbolic  link
       should be tested.

       On  success  (all  requested permissions granted), zero is returned. On
       error (at least one bit in mode asked for a permission that is  denied,
       or some other  error occurred), -1 is returned.

   OPENFILECHANNELPROC
       Function	 to  process a Tcl_FSOpenFileChannel call. Must be implemented
       for any reasonable filesystem, since any operations which require  open
       or  accessing  a	 file's contents will use it (e.g. open, encoding, and
       many Tk commands).

	      typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      int mode,
		      int permissions);

       The Tcl_FSOpenFileChannelProc opens a file specified by pathPtr and re‐
       turns  a channel handle that can be used to perform input and output on
       the file. This API is modeled after the fopen  procedure	 of  the  Unix
       standard	 I/O library. The syntax and meaning of all arguments is simi‐
       lar to those given in the Tcl open command when opening a  file,	 where
       the  mode  argument  is	a  combination	of  the	 POSIX flags O_RDONLY,
       O_WRONLY, etc. If an  error  occurs  while  opening  the	 channel,  the
       Tcl_FSOpenFileChannelProc  returns  NULL and records a POSIX error code
       that can be retrieved with Tcl_GetErrno.	 In  addition,	if  interp  is
       non-NULL,  the Tcl_FSOpenFileChannelProc leaves an error message in in‐
       terp's result after any error.

       The newly created channel must not be registered in the supplied inter‐
       preter by a Tcl_FSOpenFileChannelProc; that task is up to the caller of
       Tcl_FSOpenFileChannel (if necessary). If one of the standard  channels,
       stdin,  stdout or stderr was previously closed, the act of creating the
       new channel also assigns it as a replacement for the standard channel.

   MATCHINDIRECTORYPROC
       Function to process a Tcl_FSMatchInDirectory call. If not  implemented,
       then  glob  and	recursive  copy	 functionality	will be lacking in the
       filesystem (and this may impact commands like encoding names which  use
       glob functionality internally).

	      typedef int Tcl_FSMatchInDirectoryProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *resultPtr,
		      Tcl_Obj *pathPtr,
		      const char *pattern,
		      Tcl_GlobTypeData *types);

       The  function should return all files or directories (or other filesys‐
       tem objects) which match the given pattern and accord  with  the	 types
       specification  given.  There are two ways in which this function may be
       called. If pattern is NULL, then pathPtr is a full  path	 specification
       of a single file or directory which should be checked for existence and
       correct type. Otherwise, pathPtr is a directory, the contents of	 which
       the function should search for files or directories which have the cor‐
       rect type. In either case, pathPtr can be assumed to be	both  non-NULL
       and non-empty. It is not currently documented whether pathPtr will have
       a file separator at its end of not, so code should be flexible to  both
       possibilities.

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the matching process. Error messages are placed in  interp,
       unless interp in NULL in which case no error message need be generated;
       on a TCL_OK result, results should be  added  to	 the  resultPtr	 value
       given  (which  can  be  assumed	to  be a valid unshared Tcl list). The
       matches added to resultPtr should include  any  path  prefix  given  in
       pathPtr (this usually means they will be absolute path specifications).
       Note that if no matches are found, that simply leads to	an  empty  re‐
       sult;  errors  are only signaled for actual file or filesystem problems
       which may occur during the matching process.

       The Tcl_GlobTypeData structure passed in the types  parameter  contains
       the following fields:

	      typedef struct Tcl_GlobTypeData {
		  /* Corresponds to bcdpfls as in 'find -t' */
		  int type;
		  /* Corresponds to file permissions */
		  int perm;
		  /* Acceptable mac type */
		  Tcl_Obj *macType;
		  /* Acceptable mac creator */
		  Tcl_Obj *macCreator;
	      } Tcl_GlobTypeData;

       There are two specific cases which it is important to handle correctly,
       both when types is non-NULL. The two  cases  are	 when  types->types  &
       TCL_GLOB_TYPE_DIR  or  types->types & TCL_GLOB_TYPE_MOUNT are true (and
       in particular when the other flags are false). In the  first  of	 these
       cases,  the function must list the contained directories. Tcl uses this
       to implement recursive globbing, so it is critical that filesystems im‐
       plement	directory  matching  correctly.	 In the second of these cases,
       with TCL_GLOB_TYPE_MOUNT, the filesystem must  list  the	 mount	points
       which  lie within the given pathPtr (and in this case, pathPtr need not
       lie within the same filesystem - different to all other cases in	 which
       this  function  is  called).  Support for this is critical if Tcl is to
       have seamless transitions between from one filesystem to another.

   UTIMEPROC
       Function to process a Tcl_FSUtime call. Required to allow setting  (not
       reading)	 of  times  with  file	mtime, file atime and the open-r/open-
       w/fcopy implementation of file copy.

	      typedef int Tcl_FSUtimeProc(
		      Tcl_Obj *pathPtr,
		      struct utimbuf *tval);

       The access and modification times of  the  file	specified  by  pathPtr
       should be changed to the values given in the tval structure.

       The return value should be 0 on success and -1 on an error, as with the
       system utime.

   LINKPROC
       Function to process a Tcl_FSLink call. Should be	 implemented  only  if
       the filesystem supports links, and may otherwise be NULL.

	      typedef Tcl_Obj *Tcl_FSLinkProc(
		      Tcl_Obj *linkNamePtr,
		      Tcl_Obj *toPtr,
		      int linkAction);

       If toPtr is NULL, the function is being asked to read the contents of a
       link. The result is a Tcl_Obj specifying the contents of the link given
       by  linkNamePtr,	 or  NULL if the link could not be read. The result is
       owned by the caller (and should therefore have  its  ref	 count	incre‐
       mented before being returned). Any callers should call Tcl_DecrRefCount
       on this result when it is no longer needed.  If toPtr is not NULL,  the
       function	 should	 attempt  to  create  a link.  The result in this case
       should be toPtr if the link was successful and NULL otherwise. In  this
       case the result is not owned by the caller (i.e. no reference count ma‐
       nipulations on either  end  are	needed).  See  the  documentation  for
       Tcl_FSLink for the correct interpretation of the linkAction flags.

   LISTVOLUMESPROC
       Function	 to  list  any	filesystem  volumes  added by this filesystem.
       Should be implemented only if the filesystem adds volumes at  the  head
       of the filesystem, so that they can be returned by file volumes.

	      typedef Tcl_Obj *Tcl_FSListVolumesProc(void);

       The  result  should  be	a list of volumes added by this filesystem, or
       NULL (or an empty list) if no volumes are provided. The result value is
       considered  to  be  owned  by  the  filesystem (not by Tcl's core), but
       should be given a reference count for Tcl. Tcl will use the contents of
       the  list and then decrement that reference count. This allows filesys‐
       tems to choose whether they actually want to retain a “global list”  of
       volumes	or  not (if not, they generate the list on the fly and pass it
       to Tcl with a reference count of 1 and then forget about the  list,  if
       yes,  then  they	 simply	 increment the reference count of their global
       list and pass it to Tcl which will copy the contents and then decrement
       the count back to where it was).

       Therefore, Tcl considers return values from this proc to be read-only.

   FILEATTRSTRINGSPROC
       Function	 to  list  all	attribute  strings  which  are	valid for this
       filesystem. If not implemented the filesystem will not support the file
       attributes  command. This allows arbitrary additional information to be
       attached to files in the filesystem. If it is not implemented, there is
       no need to implement the get and set methods.

	      typedef const char *const *Tcl_FSFileAttrStringsProc(
		      Tcl_Obj *pathPtr,
		      Tcl_Obj **objPtrRef);

       The  called  function may either return an array of strings, or may in‐
       stead return NULL and place a Tcl list into the	given  objPtrRef.  Tcl
       will  take that list and first increment its reference count before us‐
       ing it.	On completion of that use, Tcl will  decrement	its  reference
       count.  Hence  if  the  list should be disposed of by Tcl when done, it
       should have a reference count of zero, and if the list  should  not  be
       disposed	 of,  the  filesystem  should ensure it returns a value with a
       reference count of at least one.

   FILEATTRSGETPROC
       Function to process a Tcl_FSFileAttrsGet call, used by file attributes.

	      typedef int Tcl_FSFileAttrsGetProc(
		      Tcl_Interp *interp,
		      int index,
		      Tcl_Obj *pathPtr,
		      Tcl_Obj **objPtrRef);

       Returns a standard Tcl return  code.  The  attribute  value  retrieved,
       which  corresponds  to the index'th element in the list returned by the
       Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if	TCL_OK
       was  returned)  and is likely to have a reference count of zero. Either
       way we must  either  store  it  somewhere  (e.g. the  Tcl  result),  or
       Incr/Decr its reference count to ensure it is properly freed.

   FILEATTRSSETPROC
       Function to process a Tcl_FSFileAttrsSet call, used by file attributes.
       If the filesystem is read-only, there is no need to implement this.

	      typedef int Tcl_FSFileAttrsSetProc(
		      Tcl_Interp *interp,
		      int index,
		      Tcl_Obj *pathPtr,
		      Tcl_Obj *objPtr);

       The attribute value of the index'th element in the list returned by the
       Tcl_FSFileAttrStringsProc should be set to the objPtr given.

   CREATEDIRECTORYPROC
       Function to process a Tcl_FSCreateDirectory call. Should be implemented
       unless the FS is read-only.

	      typedef int Tcl_FSCreateDirectoryProc(
		      Tcl_Obj *pathPtr);

       The return value is a standard Tcl result indicating whether  an	 error
       occurred	 in  the  process.  If successful, a new directory should have
       been added to the filesystem in the location specified by pathPtr.

   REMOVEDIRECTORYPROC
       Function to process a Tcl_FSRemoveDirectory call. Should be implemented
       unless the FS is read-only.

	      typedef int Tcl_FSRemoveDirectoryProc(
		      Tcl_Obj *pathPtr,
		      int recursive,
		      Tcl_Obj **errorPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the process. If  successful,	 the  directory	 specified  by
       pathPtr	should have been removed from the filesystem. If the recursive
       flag is given, then a non-empty directory should be deleted without er‐
       ror.  If	 this flag is not given, then and the directory is non-empty a
       POSIX “EEXIST” error should be signaled. If an error  does  occur,  the
       name  of	 the file or directory which caused the error should be placed
       in errorPtr.

   DELETEFILEPROC
       Function to process a Tcl_FSDeleteFile call. Should be implemented  un‐
       less the FS is read-only.

	      typedef int Tcl_FSDeleteFileProc(
		      Tcl_Obj *pathPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the process. If successful, the file specified  by  pathPtr
       should  have  been  removed  from  the  filesystem.  Note  that, if the
       filesystem supports symbolic links, Tcl will always call this  function
       and  not	 Tcl_FSRemoveDirectoryProc when needed to delete them (even if
       they are symbolic links to directories).

FILESYSTEM EFFICIENCY
       These functions need not be implemented for a particular filesystem be‐
       cause  the core has a fallback implementation available. See each indi‐
       vidual description for the consequences of leaving the field NULL.

   LSTATPROC
       Function to process a Tcl_FSLstat call. If not  implemented,  Tcl  will
       attempt	to  use	 the statProc defined above instead. Therefore it need
       only be implemented if a filesystem can differentiate between stat  and
       lstat calls.

	      typedef int Tcl_FSLstatProc(
		      Tcl_Obj *pathPtr,
		      Tcl_StatBuf *statPtr);

       The  behavior  of  this	function  is  very  similar  to	 that  of  the
       Tcl_FSStatProc defined above, except that if it is applied  to  a  sym‐
       bolic link, it returns information about the link, not about the target
       file.

   COPYFILEPROC
       Function to process a Tcl_FSCopyFile call. If not implemented Tcl  will
       fall  back  on open-r, open-w and fcopy as a copying mechanism.	There‐
       fore it need only be implemented if the filesystem can perform that ac‐
       tion more efficiently.

	      typedef int Tcl_FSCopyFileProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the copying process. Note that, destPathPtr is the name  of
       the  file  which	 should become the copy of srcPathPtr. It is never the
       name of a directory into which srcPathPtr  could	 be  copied  (i.e. the
       function is much simpler than the Tcl level file copy subcommand). Note
       that, if the filesystem supports symbolic links, Tcl will  always  call
       this  function and not copyDirectoryProc when needed to copy them (even
       if they are symbolic links to directories). Finally, if the  filesystem
       determines  it  cannot support the file copy action, calling Tcl_SetEr‐
       rno(EXDEV) and returning a non-TCL_OK result will tell Tcl to  use  its
       standard fallback mechanisms.

   RENAMEFILEPROC
       Function	 to  process  a Tcl_FSRenameFile call. If not implemented, Tcl
       will fall back on a copy and delete mechanism. Therefore it  need  only
       be  implemented	if  the	 filesystem can perform that action more effi‐
       ciently.

	      typedef int Tcl_FSRenameFileProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr);

       The return value is a standard Tcl result indicating whether  an	 error
       occurred	 in the renaming process. If the filesystem determines it can‐
       not support the file rename action, calling Tcl_SetErrno(EXDEV) and re‐
       turning	a non-TCL_OK result will tell Tcl to use its standard fallback
       mechanisms.

   COPYDIRECTORYPROC
       Function to process a Tcl_FSCopyDirectory call. If not implemented, Tcl
       will  fall  back on a recursive file mkdir, file copy mechanism. There‐
       fore it need only be implemented if the filesystem can perform that ac‐
       tion more efficiently.

	      typedef int Tcl_FSCopyDirectoryProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr,
		      Tcl_Obj **errorPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the copying process. If an error does occur,	 the  name  of
       the  file  or  directory which caused the error should be placed in er‐
       rorPtr. Note that, destPathPtr is the name of the directory-name	 which
       should  become  the mirror-image of srcPathPtr. It is not the name of a
       directory into which srcPathPtr should be copied (i.e. the function  is
       much  simpler than the Tcl level file copy subcommand). Finally, if the
       filesystem determines it cannot	support	 the  directory	 copy  action,
       calling Tcl_SetErrno(EXDEV) and returning a non-TCL_OK result will tell
       Tcl to use its standard fallback mechanisms.

   LOADFILEPROC
       Function to process a Tcl_FSLoadFile call. If not implemented, Tcl will
       fall back on a copy to native-temp followed by a Tcl_FSLoadFile on that
       temporary copy. Therefore it need only be implemented if the filesystem
       can  load  code	directly,  or  it  can be implemented simply to return
       TCL_ERROR to disable load functionality in this filesystem entirely.

	      typedef int Tcl_FSLoadFileProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      Tcl_LoadHandle *handlePtr,
		      Tcl_FSUnloadFileProc *unloadProcPtr);

       Returns a standard Tcl completion code. If an error  occurs,  an	 error
       message	is left in the interp's result. The function dynamically loads
       a binary code file into memory. On a  successful	 load,	the  handlePtr
       should  be filled with a token for the dynamically loaded file, and the
       unloadProcPtr should be filled in with the address of a procedure.  The
       unload  procedure  will	be called with the given Tcl_LoadHandle as its
       only parameter when Tcl needs to unload the file. For example, for  the
       native  filesystem,  the	 Tcl_LoadHandle	 returned is currently a token
       which can be used in the private TclpFindSymbol to access functions  in
       the  new	 code. Each filesystem is free to define the Tcl_LoadHandle as
       it requires. Finally, if the filesystem determines  it  cannot  support
       the  file load action, calling Tcl_SetErrno(EXDEV) and returning a non-
       TCL_OK result will tell Tcl to use its standard fallback mechanisms.

   UNLOADFILEPROC
       Function to unload a previously successfully loaded file. If  load  was
       implemented,  then  this	 should	 also  be implemented, if there is any
       cleanup action required.

	      typedef void Tcl_FSUnloadFileProc(
		      Tcl_LoadHandle loadHandle);

   GETCWDPROC
       Function to process a Tcl_FSGetCwd call. Most filesystems need not  im‐
       plement	this. It will usually only be called once, if getcwd is called
       before chdir. May be NULL.

	      typedef Tcl_Obj *Tcl_FSGetCwdProc(
		      Tcl_Interp *interp);

       If the filesystem supports a native notion of a current working	direc‐
       tory  (which  might  perhaps  change independent of Tcl), this function
       should return that cwd as the result, or NULL if the current  directory
       could  not  be determined (e.g. the user does not have appropriate per‐
       missions on the cwd directory). If NULL is returned, an	error  message
       is left in the interp's result.

   CHDIRPROC
       Function to process a Tcl_FSChdir call. If filesystems do not implement
       this, it will be emulated by a series of directory access checks.  Oth‐
       erwise,	virtual	 filesystems  which  do implement it need only respond
       with a positive return result if the pathPtr is a valid, accessible di‐
       rectory	in  their filesystem. They need not remember the result, since
       that will be automatically remembered for use  by  Tcl_FSGetCwd.	  Real
       filesystems  should carry out the correct action (i.e. call the correct
       system chdir API).

	      typedef int Tcl_FSChdirProc(
		      Tcl_Obj *pathPtr);

       The Tcl_FSChdirProc changes the applications current working  directory
       to  the value specified in pathPtr. The function returns -1 on error or
       0 on success.

SEE ALSO
       cd(n), file(n), filename(n), load(n), open(n), pwd(n),  source(n),  un‐
       load(n)

KEYWORDS
       stat, access, filesystem, vfs, virtual filesystem



Tcl				      8.4			 Filesystem(3)

Filesystem(3)		    Tcl Library Procedures		 Filesystem(3)



______________________________________________________________________________

NAME
       Tcl_FSRegister,	 Tcl_FSUnregister,   Tcl_FSData,  Tcl_FSMountsChanged,
       Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile,  Tcl_FS‐
       CopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDi‐
       rectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile,  Tcl_FSE‐
       valFileEx,  Tcl_FSLoadFile,  Tcl_FSUnloadFile,  Tcl_FSMatchInDirectory,
       Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAt‐
       trsSet,	Tcl_FSFileAttrStrings,	Tcl_FSStat,  Tcl_FSAccess, Tcl_FSOpen‐
       FileChannel,    Tcl_FSGetCwd,	 Tcl_FSChdir,	  Tcl_FSPathSeparator,
       Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalized‐
       Path, Tcl_FSJoinToPath, Tcl_FSConvertToPathType,	 Tcl_FSGetInternalRep,
       Tcl_FSGetTranslatedPath,	  Tcl_FSGetTranslatedStringPath,  Tcl_FSNewNa‐
       tivePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_GetAccessTime‐
       FromStat,	Tcl_GetBlockSizeFromStat,	Tcl_GetBlocksFromStat,
       Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat,  Tcl_GetFSDevice‐
       FromStat,	Tcl_GetFSInodeFromStat,	       Tcl_GetGroupIdFromStat,
       Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTime‐
       FromStat,  Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, Tcl_AllocStatBuf
       - procedures to interact with any filesystem

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_FSRegister(clientData, fsPtr)

       int
       Tcl_FSUnregister(fsPtr)

       void *
       Tcl_FSData(fsPtr)

       Tcl_FSMountsChanged(fsPtr)

       const Tcl_Filesystem *
       Tcl_FSGetFileSystemForPath(pathPtr)

       Tcl_PathType
       Tcl_FSGetPathType(pathPtr)

       int
       Tcl_FSCopyFile(srcPathPtr, destPathPtr)

       int
       Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)

       int
       Tcl_FSCreateDirectory(pathPtr)

       int
       Tcl_FSDeleteFile(pathPtr)

       int
       Tcl_FSRemoveDirectory(pathPtr, recursive, errorPtr)

       int
       Tcl_FSRenameFile(srcPathPtr, destPathPtr)

       Tcl_Obj *
       Tcl_FSListVolumes(void)

       int
       Tcl_FSEvalFileEx(interp, pathPtr, encodingName)

       int
       Tcl_FSEvalFile(interp, pathPtr)

       int
       Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
		      loadHandlePtr, unloadProcPtr)

       int								       │
       Tcl_FSUnloadFile(interp, loadHandle)				       │

       int
       Tcl_FSMatchInDirectory(interp, resultPtr, pathPtr, pattern, types)

       Tcl_Obj *
       Tcl_FSLink(linkNamePtr, toPtr, linkAction)

       int
       Tcl_FSLstat(pathPtr, statPtr)

       int
       Tcl_FSUtime(pathPtr, tval)

       int
       Tcl_FSFileAttrsGet(interp, index, pathPtr, objPtrRef)

       int
       Tcl_FSFileAttrsSet(interp, index, pathPtr, objPtr)

       const char *const *
       Tcl_FSFileAttrStrings(pathPtr, objPtrRef)

       int
       Tcl_FSStat(pathPtr, statPtr)

       int
       Tcl_FSAccess(pathPtr, mode)

       Tcl_Channel
       Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)

       Tcl_Obj *
       Tcl_FSGetCwd(interp)

       int
       Tcl_FSChdir(pathPtr)

       Tcl_Obj *
       Tcl_FSPathSeparator(pathPtr)

       Tcl_Obj *
       Tcl_FSJoinPath(listObj, elements)

       Tcl_Obj *
       Tcl_FSSplitPath(pathPtr, lenPtr)

       int
       Tcl_FSEqualPaths(firstPtr, secondPtr)

       Tcl_Obj *
       Tcl_FSGetNormalizedPath(interp, pathPtr)

       Tcl_Obj *
       Tcl_FSJoinToPath(basePtr, objc, objv)

       int
       Tcl_FSConvertToPathType(interp, pathPtr)

       void *
       Tcl_FSGetInternalRep(pathPtr, fsPtr)

       Tcl_Obj *
       Tcl_FSGetTranslatedPath(interp, pathPtr)

       const char *
       Tcl_FSGetTranslatedStringPath(interp, pathPtr)

       Tcl_Obj *
       Tcl_FSNewNativePath(fsPtr, clientData)

       const void *
       Tcl_FSGetNativePath(pathPtr)

       Tcl_Obj *
       Tcl_FSFileSystemInfo(pathPtr)

       Tcl_StatBuf *
       Tcl_AllocStatBuf()

       Tcl_WideInt							       │
       Tcl_GetAccessTimeFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetBlockSizeFromStat(statPtr)				       │

       Tcl_WideUInt							       │
       Tcl_GetBlocksFromStat(statPtr)					       │

       Tcl_WideInt							       │
       Tcl_GetChangeTimeFromStat(statPtr)				       │

       int								       │
       Tcl_GetDeviceTypeFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetFSDeviceFromStat(statPtr)					       │

       unsigned								       │
       Tcl_GetFSInodeFromStat(statPtr)					       │

       int								       │
       Tcl_GetGroupIdFromStat(statPtr)					       │

       int								       │
       Tcl_GetLinkCountFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetModeFromStat(statPtr)					       │

       Tcl_WideInt							       │
       Tcl_GetModificationTimeFromStat(statPtr)				       │

       Tcl_WideUInt							       │
       Tcl_GetSizeFromStat(statPtr)					       │

       int								       │
       Tcl_GetUserIdFromStat(statPtr)					       │

ARGUMENTS
       const Tcl_Filesystem *fsPtr (in)		   Points to a structure  con‐
						   taining  the	 addresses  of
						   procedures  that   can   be
						   called to perform the vari‐
						   ous filesystem operations.

       Tcl_Obj *pathPtr (in)			   The	path  represented   by
						   this	 value is used for the
						   operation in	 question.  If
						   the	value does not already
						   have an internal path  rep‐
						   resentation,	  it  will  be
						   converted to have one.

       Tcl_Obj *srcPathPtr (in)			   As for  pathPtr,  but  used
						   for	the  source file for a
						   copy or rename operation.

       Tcl_Obj *destPathPtr (in)		   As for  pathPtr,  but  used
						   for	the  destination file‐
						   name for a copy  or	rename
						   operation.

       int recursive (in)			   Whether to remove subdirec‐
						   tories and  their  contents
						   as well.

       const char *encodingName (in)		   The	encoding  of  the data
						   stored in the file  identi‐
						   fied	 by  pathPtr and to be
						   evaluated.

       const char *pattern (in)			   Only files  or  directories
						   matching  this pattern will
						   be returned.

       Tcl_GlobTypeData *types (in)		   Only files  or  directories
						   matching  the type descrip‐
						   tions  contained  in	  this
						   structure will be returned.
						   This parameter may be NULL.

       Tcl_Interp *interp (in)			   Interpreter to  use	either
						   for results, evaluation, or
						   reporting error messages.

       void *clientData (in)			   The native  description  of
						   the path value to create.

       Tcl_Obj *firstPtr (in)			   The	first of two path val‐
						   ues to compare.  The	 value
						   may	be  converted  to path
						   type.

       Tcl_Obj *secondPtr (in)			   The second of two path val‐
						   ues	to  compare. The value
						   may be  converted  to  path
						   type.

       Tcl_Obj *listObj (in)			   The	list  of path elements
						   to operate on with  a  join
						   operation.

       int elements (in)			   The	number	of elements in
						   the listObj which should be
						   joined  together.  If nega‐
						   tive, then all elements are
						   joined.

       Tcl_Obj **errorPtr (out)			   In  the  case  of an error,
						   filled with	a  value  con‐
						   taining  the	 name  of  the
						   file which caused an	 error
						   in  the various copy/rename
						   operations.

       int index (in)				   The index of the  attribute
						   in question.

       Tcl_Obj *objPtr (in)			   The value to set in the op‐
						   eration.

       Tcl_Obj **objPtrRef (out)		   Filled with	a  value  con‐
						   taining  the	 result of the
						   operation.

       Tcl_Obj *resultPtr (out)			   Preallocated value in which
						   to store (using Tcl_ListOb‐
						   jAppendElement) the list of
						   files  or directories which
						   are successfully matched.

       int mode (in)				   Mask consisting of  one  or
						   more	 of  R_OK,  W_OK, X_OK
						   and F_OK.  R_OK,  W_OK  and
						   X_OK	   request    checking
						   whether the file exists and
						   has	 read, write and  exe‐
						   cute	 permissions,  respec‐
						   tively.  F_OK just requests
						   checking for the  existence
						   of the file.

       Tcl_StatBuf *statPtr (out)		   The structure that contains
						   the result  of  a  stat  or
						   lstat operation.

       const char *sym1 (in)			   Name of a procedure to look
						   up in the file's symbol ta‐
						   ble

       const char *sym2 (in)			   Name of a procedure to look
						   up in the file's symbol ta‐
						   ble

       Tcl_PackageInitProc **proc1Ptr (out)	   Filled  with the init func‐
						   tion for this code.

       Tcl_PackageInitProc **proc2Ptr (out)	   Filled with	the  safe-init
						   function for this code.

       void **clientDataPtr (out)		   Filled  with the clientData
						   value  to  pass   to	  this
						   code's unload function when
						   it is called.

       Tcl_LoadHandle *loadHandlePtr (out)	   Filled with an abstract to‐
						   ken representing the loaded
						   file.

       Tcl_FSUnloadFileProc **unloadProcPtr (out)  Filled with the function to
						   use to unload this piece of
						   code.

       Tcl_LoadHandle loadHandle (in)		   Handle to  the  loaded  li‐
						   brary to be unloaded.

       utimbuf *tval (in)			   The access and modification
						   times in this structure are
						   read	 and used to set those
						   values for a given file.

       const char *modeString (in)		   Specifies how the  file  is
						   to  be  accessed.  May have
						   any of the  values  allowed
						   for	the  mode  argument to
						   the Tcl open command.

       int permissions (in)			   POSIX-style	    permission
						   flags  such	as  0644. If a
						   new file is created,	 these
						   permissions	will be set on
						   the created file.

       int *lenPtr (out)			   If  non-NULL,  filled  with
						   the	number	of elements in
						   the split path.

       Tcl_Obj *basePtr (in)			   The base path on  to	 which
						   to join the given elements.
						   May be NULL.

       int objc (in)				   The number of  elements  in
						   objv.

       Tcl_Obj *const objv[] (in)		   The elements to join to the
						   given base path.

       Tcl_Obj *linkNamePtr (in)		   The name of the link to  be
						   created or read.

       Tcl_Obj *toPtr (in)			   What	   the	 link	called
						   linkNamePtr	  should    be
						   linked  to,	or NULL if the
						   symbolic link specified  by
						   linkNamePtr is to be read.

       int linkAction (in)			   OR-ed  combination of flags
						   indicating  what  kind   of
						   link	  should   be  created
						   (will be ignored  if	 toPtr
						   is NULL). Valid bits to set
						   are	       TCL_CREATE_SYM‐
						   BOLIC_LINK	and   TCL_CRE‐
						   ATE_HARD_LINK.   When  both
						   flags  are  set and the un‐
						   derlying filesystem can  do
						   either,  symbolic links are
						   preferred.
______________________________________________________________________________

DESCRIPTION
       There  are  several  reasons  for  calling  the	Tcl_FS	API  functions
       (e.g. Tcl_FSAccess  and	Tcl_FSStat)  rather  than calling system level
       functions like access and stat directly. First, they will  work	cross-
       platform,  so  an  extension which calls them should work unmodified on
       Unix and Windows. Second, the Windows implementation of some  of	 these
       functions fixes some bugs in the system level calls. Third, these func‐
       tion calls deal with any	 “Utf  to  platform-native”  path  conversions
       which  may  be  required (and may cache the results of such conversions
       for greater efficiency on subsequent calls). Fourth, and	 perhaps  most
       importantly,  all  of  these  functions are “virtual filesystem aware”.
       Any virtual filesystem  (VFS  for  short)  which	 has  been  registered
       (through	 Tcl_FSRegister)  may reroute file access to alternative media
       or access methods. This means that all of these functions  (and	there‐
       fore  the  corresponding	 file, glob, pwd, cd, open, etc. Tcl commands)
       may be operate on “files” which are not	native	files  in  the	native
       filesystem.  This  also means that any Tcl extension which accesses the
       filesystem (FS for short) through this API  is  automatically  “virtual
       filesystem  aware”.   Of	 course,  if  an extension accesses the native
       filesystem directly (through platform-specific APIs, for example), then
       Tcl cannot intercept such calls.

       If appropriate VFSes have been registered, the “files” may, to give two
       examples, be remote (e.g. situated on a remote ftp server) or  archived
       (e.g. lying inside a .zip archive). Such registered filesystems provide
       a lookup table of functions to implement all or some of the functional‐
       ity listed here. Finally, the Tcl_FSStat and Tcl_FSLstat calls abstract
       away from what the “struct stat” buffer is actually declared to be, al‐
       lowing  the same code to be used both on systems with and systems with‐
       out support for files larger than 2GB in size.

       The Tcl_FS API is Tcl_Obj-ified and may cache internal  representations
       and  other  path-related	 strings (e.g. the current working directory).
       One side-effect of this is that one must not pass in values with a ref‐
       erence count of zero to any of these functions. If such calls were han‐
       dled, they might result in memory leaks (under some circumstances,  the
       filesystem  code may wish to retain a reference to the passed in value,
       and so one must not assume that after any of these  calls  return,  the
       value  still  has  a  reference count of zero - it may have been incre‐
       mented) or in a direct segmentation fault (or other memory  access  er‐
       ror)  due  to  the value being freed part way through the complex value
       manipulation required to ensure that the path is fully  normalized  and
       absolute	 for  filesystem  determination. The practical lesson to learn
       from this is that

	      Tcl_Obj *path = Tcl_NewStringObj(...);
	      Tcl_FSWhatever(path);
	      Tcl_DecrRefCount(path);

       is wrong, and may cause memory errors. The path must have its reference
       count  incremented  before  passing it in, or decrementing it. For this
       reason, values with a reference count of zero are considered not to  be
       valid  filesystem paths and calling any Tcl_FS API function with such a
       value will result in no action being taken.

   FS API FUNCTIONS
       Tcl_FSCopyFile attempts to copy the file given  by  srcPathPtr  to  the
       path  name given by destPathPtr. If the two paths given lie in the same
       filesystem (according to Tcl_FSGetFileSystemForPath) then that filesys‐
       tem's  “copy  file”  function is called (if it is non-NULL).  Otherwise
       the function returns -1 and sets the errno global  C  variable  to  the
       “EXDEV” POSIX error code (which signifies a “cross-domain link”).

       Tcl_FSCopyDirectory  attempts to copy the directory given by srcPathPtr
       to the path name given by destPathPtr. If the two paths	given  lie  in
       the same filesystem (according to Tcl_FSGetFileSystemForPath) then that
       filesystem's “copy file” function is called (if it is non-NULL).	  Oth‐
       erwise  the function returns -1 and sets the errno global C variable to
       the “EXDEV” POSIX error code (which signifies a “cross-domain link”).

       Tcl_FSCreateDirectory attempts to create the directory given by pathPtr
       by calling the owning filesystem's “create directory” function.

       Tcl_FSDeleteFile	 attempts to delete the file given by pathPtr by call‐
       ing the owning filesystem's “delete file” function.

       Tcl_FSRemoveDirectory attempts to remove the directory given by pathPtr
       by calling the owning filesystem's “remove directory” function.

       Tcl_FSRenameFile attempts to rename the file or directory given by src‐
       PathPtr to the path name given by destPathPtr. If the two  paths	 given
       lie  in	the  same filesystem (according to Tcl_FSGetFileSystemForPath)
       then that filesystem's “rename file” function is called (if it is  non-
       NULL).  Otherwise  the  function returns -1 and sets the errno global C
       variable to the “EXDEV” POSIX error code (which signifies a  “cross-do‐
       main link”).

       Tcl_FSListVolumes calls each filesystem which has a non-NULL “list vol‐
       umes” function and asks them to return their list of root  volumes.  It
       accumulates the return values in a list which is returned to the caller
       (with a reference count of 0).

       Tcl_FSEvalFileEx reads the file given by	 pathPtr  using	 the  encoding
       identified  by encodingName and evaluates its contents as a Tcl script.
       It returns the same information as Tcl_EvalObjEx.  If  encodingName  is
       NULL,  the  system  encoding is used for reading the file contents.  If
       the file could not be read then a Tcl error is returned to describe why
       the  file  could not be read.  The eofchar for files is “\x1A” (^Z) for
       all platforms.  If you require a “^Z” in code  for  string  comparison,
       you  can use “\x1A”, which will be safely substituted by the Tcl inter‐
       preter into “^Z”.  Tcl_FSEvalFile is a simpler version  of  Tcl_FSEval‐
       FileEx that always uses the system encoding when reading the file.

       Tcl_FSLoadFile dynamically loads a binary code file into memory and re‐
       turns the addresses of two procedures within that file, if they are de‐
       fined. The appropriate function for the filesystem to which pathPtr be‐
       longs will be called. If that filesystem does not implement this	 func‐
       tion  (most  virtual filesystems will not, because of OS limitations in
       dynamically loading binary code), Tcl will attempt to copy the file  to
       a  temporary  directory and load that temporary file.  Tcl_FSUnloadFile │
       reverses the operation, asking for the library indicated by  the	 load‐ │
       Handle  to  be removed from the process. Note that, unlike with the un‐ │
       load command, this does not give the library any opportunity  to	 clean │
       up.

       Both  the  above functions return a standard Tcl completion code. If an
       error occurs, an error message is left in the interp's result.

       The token provided via the variable indicated by loadHandlePtr  may  be │
       used with Tcl_FindSymbol.

       Tcl_FSMatchInDirectory  is used by the globbing code to search a direc‐
       tory for all files which match a given pattern. The  appropriate	 func‐
       tion for the filesystem to which pathPtr belongs will be called.

       The  return  value is a standard Tcl result indicating whether an error
       occurred in globbing. Error messages are placed in interp  (unless  in‐
       terp is NULL, which is allowed), but good results are placed in the re‐
       sultPtr given.

       Note that the glob code implements recursive  patterns  internally,  so
       this  function  will  only ever be passed simple patterns, which can be
       matched using the logic of string match. To handle recursion, Tcl  will
       call  this  function  frequently	 asking only for directories to be re‐
       turned. A special case of being called with a  NULL  pattern  indicates
       that the path needs to be checked only for the correct type.

       Tcl_FSLink  replaces the library version of readlink, and extends it to
       support the  creation  of  links.  The  appropriate  function  for  the
       filesystem to which linkNamePtr belongs will be called.

       If  the toPtr is NULL, a “read link” action is performed. The result is
       a Tcl_Obj specifying  the  contents  of	the  symbolic  link  given  by
       linkNamePtr, or NULL if the link could not be read. The result is owned
       by the caller, which should call Tcl_DecrRefCount when the result is no
       longer  needed.	If  the toPtr is not NULL, Tcl should create a link of
       one of the types passed in in the linkAction flag.   This  flag	is  an
       OR'ed combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CREATE_HARD_LINK.
       Where a choice exists (i.e. more than one flag is passed in),  the  Tcl
       convention  is  to  prefer  symbolic links. When a link is successfully
       created, the return value should be toPtr (which is  therefore  already
       owned by the caller). If unsuccessful, NULL is returned.

       Tcl_FSLstat  fills  the	Tcl_StatBuf structure statPtr with information
       about the specified file. You do not need any access rights to the file
       to  get	this information but you need search rights to all directories
       named in the path leading to the file. The  Tcl_StatBuf	structure  in‐
       cludes  info  regarding	device, inode (always 0 on Windows), privilege
       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
       id  (always 0 on Windows), rdev (same as device on Windows), size, last
       access time, last modification time, and	 last  metadata	 change	 time.
       See PORTABLE STAT RESULT API for a description of how to write portable
       code to allocate and access the Tcl_StatBuf structure.

       If path exists, Tcl_FSLstat returns 0 and the stat structure is	filled
       with data. Otherwise, -1 is returned, and no stat info is given.

       Tcl_FSUtime replaces the library version of utime.

       This  returns 0 on success and -1 on error (as per the utime documenta‐
       tion). If successful, the function will update the “atime” and  “mtime”
       values of the file given.

       Tcl_FSFileAttrsGet  implements  read  access  for the hookable file at‐
       tributes subcommand. The appropriate function  for  the	filesystem  to
       which pathPtr belongs will be called.

       If  the	result	is TCL_OK, then a value was placed in objPtrRef, which
       will only be temporarily valid (unless Tcl_IncrRefCount is called).

       Tcl_FSFileAttrsSet implements write access for the  hookable  file  at‐
       tributes	 subcommand.  The  appropriate	function for the filesystem to
       which pathPtr belongs will be called.

       Tcl_FSFileAttrStrings implements part of the hookable  file  attributes
       subcommand.  The appropriate function for the filesystem to which path‐
       Ptr belongs will be called.

       The called procedure may either return an array of strings, or may  in‐
       stead  return  NULL  and place a Tcl list into the given objPtrRef. Tcl
       will take that list and first increment its reference count before  us‐
       ing  it.	  On  completion of that use, Tcl will decrement its reference
       count. Hence if the list should be disposed of by  Tcl  when  done,  it
       should  have  a	reference count of zero, and if the list should not be
       disposed of, the filesystem should ensure it retains a reference	 count
       to the value.

       Tcl_FSAccess checks whether the process would be allowed to read, write
       or test for existence of the file (or other  filesystem	object)	 whose
       name  is pathname. If pathname is a symbolic link on Unix, then permis‐
       sions of the file referred by this symbolic link are tested.

       On success (all requested permissions granted), zero  is	 returned.  On
       error  (at least one bit in mode asked for a permission that is denied,
       or some other error occurred), -1 is returned.

       Tcl_FSStat fills the Tcl_StatBuf	 structure  statPtr  with  information
       about the specified file. You do not need any access rights to the file
       to get this information but you need search rights to  all  directories
       named  in  the  path leading to the file. The Tcl_StatBuf structure in‐
       cludes info regarding device, inode (always 0  on  Windows),  privilege
       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
       id (always 0 on Windows), rdev (same as device on Windows), size,  last
       access  time,  last  modification  time, and last metadata change time.
       See PORTABLE STAT RESULT API for a description of how to write portable
       code to allocate and access the Tcl_StatBuf structure.

       If  path	 exists, Tcl_FSStat returns 0 and the stat structure is filled
       with data. Otherwise, -1 is returned, and no stat info is given.

       Tcl_FSOpenFileChannel opens a file specified by pathPtr and  returns  a
       channel	handle	that  can  be  used to perform input and output on the
       file. This API is modeled after the fopen procedure of the  Unix	 stan‐
       dard  I/O  library.  The syntax and meaning of all arguments is similar
       to those given in the Tcl open command when opening a file.  If an  er‐
       ror  occurs  while  opening  the channel, Tcl_FSOpenFileChannel returns
       NULL and records	 a  POSIX  error  code	that  can  be  retrieved  with
       Tcl_GetErrno.   In addition, if interp is non-NULL, Tcl_FSOpenFileChan‐
       nel leaves an error message in interp's result after any error.

       The newly created channel is not	 registered  in	 the  supplied	inter‐
       preter;	to  register it, use Tcl_RegisterChannel.  If one of the stan‐
       dard channels, stdin, stdout or stderr was previously closed,  the  act
       of  creating  the  new channel also assigns it as a replacement for the
       standard channel.

       Tcl_FSGetCwd replaces the library version of getcwd.

       It returns the Tcl library's current working  directory.	 This  may  be
       different  to  the  native  platform's working directory, which happens
       when the current working directory is not in the native filesystem.

       The result is a pointer to a Tcl_Obj specifying the current  directory,
       or  NULL	 if  the current directory could not be determined. If NULL is
       returned, an error message is left in the interp's result.

       The result already has its reference count incremented for the  caller.
       When  it	 is  no	 longer	 needed, that reference count should be decre‐
       mented. This is needed for thread-safety purposes,  to  allow  multiple
       threads	to  access  this and related functions, while ensuring the re‐
       sults are always valid.

       Tcl_FSChdir replaces the library version of chdir. The path is  normal‐
       ized  and  then	passed	to  the	 filesystem  which  claims it. If that
       filesystem does not implement this function, Tcl	 will  fallback	 to  a
       combination  of	stat  and access to check whether the directory exists
       and has appropriate permissions.

       For results, see chdir documentation. If successful, we keep  a	record
       of  the	successful  path in cwdPathPtr for subsequent calls to Tcl_FS‐
       GetCwd.

       Tcl_FSPathSeparator returns the separator character to be used for most
       specific	 element  of the path specified by pathPtr (i.e. the last part
       of the path).

       The separator is returned as a Tcl_Obj containing a string of length 1.
       If the path is invalid, NULL is returned.

       Tcl_FSJoinPath  takes  the  given  Tcl_Obj,  which must be a valid list
       (which is allowed to have a reference count of zero), and  returns  the
       path  value  given  by considering the first elements elements as valid
       path segments (each path segment may be a complete path, a partial path
       or  just a single possible directory or file name). If any path segment
       is actually an absolute path, then all prior  path  segments  are  dis‐
       carded.	If elements is less than 0, we use the entire list.

       It  is  possible	 that the returned value is actually an element of the
       given list, so the caller should be careful to increment the  reference
       count of the result before freeing the list.

       The  returned  value,  typically with a reference count of zero (but it
       could be shared under some conditions), contains the joined  path.  The
       caller must add a reference count to the value before using it. In par‐
       ticular, the returned value could be an element of the given  list,  so
       freeing the list might free the value prematurely if no reference count
       has been taken.	If the number of elements is zero, then	 the  returned
       value will be an empty-string Tcl_Obj.

       Tcl_FSSplitPath	takes the given Tcl_Obj, which should be a valid path,
       and returns a Tcl list value containing each segment of that path as an
       element.	  It  returns  a list value with a reference count of zero. If
       the passed in lenPtr is non-NULL, the variable it points to will be up‐
       dated to contain the number of elements in the returned list.

       Tcl_FSEqualPaths	 tests	whether the two paths given represent the same
       filesystem object.  It returns 1 if the paths are equal, and 0 if  they
       are different. If either path is NULL, 0 is always returned.

       Tcl_FSGetNormalizedPath	attempts  to  extract from the given Tcl_Obj a
       unique normalized path representation, whose string value can  be  used
       as a unique identifier for the file.

       It returns the normalized path value, owned by Tcl, or NULL if the path
       was invalid or could otherwise not be successfully converted.   Extrac‐
       tion  of	 absolute,  normalized	paths  is  very efficient (because the
       filesystem operates on these representations internally), although  the
       result  when the filesystem contains numerous symbolic links may not be
       the most user-friendly version of a path. The return value is owned  by
       Tcl and has a lifetime equivalent to that of the pathPtr passed in (un‐
       less that is a relative path, in which case the normalized  path	 value
       may  be	freed any time the cwd changes) - the caller can of course in‐
       crement the reference count if it wishes to maintain a copy for longer.

       Tcl_FSJoinToPath takes the given value, which should usually be a valid
       path or NULL, and joins onto it the array of paths segments given.

       Returns	a  value, typically with reference count of zero (but it could
       be shared under some  conditions),  containing  the  joined  path.  The
       caller  must add a reference count to the value before using it. If any
       of the values passed into this function (pathPtr or path elements) have
       a  reference  count  of zero, they will be freed when this function re‐
       turns.

       Tcl_FSConvertToPathType tries to convert the given Tcl_Obj to  a	 valid
       Tcl path type, taking account of the fact that the cwd may have changed
       even if this value is already supposedly	 of  the  correct  type.   The
       filename may begin with “~” (to indicate current user's home directory)
       or “~<user>” (to indicate any user's home directory).

       If the conversion succeeds (i.e. the value is a valid path  in  one  of
       the  current filesystems), then TCL_OK is returned. Otherwise TCL_ERROR
       is returned, and an error message may be left in the interpreter.

       Tcl_FSGetInternalRep extracts the internal representation  of  a	 given
       path  value,  in	 the  given filesystem. If the path value belongs to a
       different filesystem, we return NULL. If the internal representation is
       currently  NULL, we attempt to generate it, by calling the filesystem's
       Tcl_FSCreateInternalRepProc.

       Returns NULL or a valid internal	 path  representation.	This  internal
       representation  is cached, so that repeated calls to this function will
       not require additional conversions.

       Tcl_FSGetTranslatedPath attempts to extract the	translated  path  from
       the given Tcl_Obj.

       If  the	translation succeeds (i.e. the value is a valid path), then it
       is returned. Otherwise NULL will be returned, and an error message  may
       be  left	 in the interpreter. A “translated” path is one which contains
       no “~” or “~user” sequences (these have been expanded to their  current
       representation  in  the filesystem). The value returned is owned by the
       caller, which must store it or call Tcl_DecrRefCount to	ensure	memory
       is  freed.  This function is of little practical use, and Tcl_FSGetNor‐
       malizedPath or Tcl_FSGetNativePath are usually better functions to  use
       for most purposes.

       Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
       but returns a character string or NULL.	The string returned is dynami‐
       cally  allocated	 and  owned by the caller, which must store it or call
       ckfree to ensure it is freed. Again, Tcl_FSGetNormalizedPath or Tcl_FS‐
       GetNativePath are usually better functions to use for most purposes.

       Tcl_FSNewNativePath  performs  something	 like the reverse of the usual
       obj->path->nativerep conversions. If some code retrieves a path in  na‐
       tive form (from, e.g. readlink or a native dialog), and that path is to
       be used at the Tcl level, then calling this function  is	 an  efficient
       way of creating the appropriate path value type.

       The  resulting  value is a pure “path” value, which will only receive a
       UTF-8 string representation if that is required by some Tcl code.

       Tcl_FSGetNativePath is for use by the Win/Unix native  filesystems,  so
       that  they can easily retrieve the native (char* or TCHAR*) representa‐
       tion of a path. This function is a convenience wrapper  around  Tcl_FS‐
       GetInternalRep.	It  may be desirable in the future to have non-string-
       based native representations (for example, on macOS,  a	representation
       using  a fileSpec of FSRef structure would probably be more efficient).
       On Windows a full Unicode representation would allow for paths  of  un‐
       limited	length.	 Currently  the	 representation	 is simply a character
       string which may contain either the relative path or a complete,	 abso‐
       lute normalized path in the native encoding (complex conditions dictate
       which of these will be provided, so neither can be relied upon,	unless
       the path is known to be absolute). If you need a native path which must
       be absolute, then you should ask for the native version of a normalized
       path.  If for some reason a non-absolute, non-normalized version of the
       path is needed, that must be constructed separately (e.g. using Tcl_FS‐
       GetTranslatedPath).

       The  native  representation  is	cached	so that repeated calls to this
       function will not require additional conversions. The return  value  is
       owned  by  Tcl  and  has	 a  lifetime equivalent to that of the pathPtr
       passed in (unless that is a relative path, in  which  case  the	native
       representation may be freed any time the cwd changes).

       Tcl_FSFileSystemInfo  returns a list of two elements. The first element
       is the name  of	the  filesystem	 (e.g.	 “native”,  “vfs”,  “zip”,  or
       “prowrap”, perhaps), and the second is the particular type of the given
       path within that filesystem (which is filesystem dependent). The second
       element may be empty if the filesystem does not provide a further cate‐
       gorization of files.

       A valid list value is returned, unless the path	value  is  not	recog‐
       nized, when NULL will be returned.

       Tcl_FSGetFileSystemForPath  returns  a  pointer	to  the Tcl_Filesystem
       which accepts this path as valid.

       If no filesystem will accept the path, NULL is returned.

       Tcl_FSGetPathType determines whether the given path is relative to  the
       current directory, relative to the current volume, or absolute.

       It    returns   one   of	  TCL_PATH_ABSOLUTE,   TCL_PATH_RELATIVE,   or
       TCL_PATH_VOLUME_RELATIVE

   PORTABLE STAT RESULT API
       Tcl_AllocStatBuf allocates a Tcl_StatBuf on the system heap (which  may
       be  deallocated	by  being passed to ckfree). This allows extensions to
       invoke Tcl_FSStat and Tcl_FSLstat without being dependent on  the  size
       of the buffer. That in turn depends on the flags used to build Tcl.

       The  portable  fields  of a Tcl_StatBuf may be read using the following │
       functions, each of which returns the value of the  corresponding	 field │
       listed  in  the	table  below. Note that on some platforms there may be │
       other fields in the Tcl_StatBuf as it is an alias for a suitable system │
       structure, but only the portable ones are made available here. See your │
       system documentation for a full description of these fields.	       │

	      Access Function			 Field			       │
	       Tcl_GetFSDeviceFromStat		  st_dev		       │
	       Tcl_GetFSInodeFromStat		  st_ino		       │
	       Tcl_GetModeFromStat		  st_mode		       │
	       Tcl_GetLinkCountFromStat		  st_nlink		       │
	       Tcl_GetUserIdFromStat		  st_uid		       │
	       Tcl_GetGroupIdFromStat		  st_gid		       │
	       Tcl_GetDeviceTypeFromStat	  st_rdev		       │
	       Tcl_GetAccessTimeFromStat	  st_atime		       │
	       Tcl_GetModificationTimeFromStat	  st_mtime		       │
	       Tcl_GetChangeTimeFromStat	  st_ctime		       │
	       Tcl_GetSizeFromStat		  st_size		       │
	       Tcl_GetBlocksFromStat		  st_blocks		       │
	       Tcl_GetBlockSizeFromStat		  st_blksize		       │


THE VIRTUAL FILESYSTEM API
       A filesystem provides a Tcl_Filesystem structure that contains pointers
       to  functions  that  implement  the various operations on a filesystem;
       these operations are invoked as needed by the generic layer, which gen‐
       erally occurs through the functions listed above.

       The Tcl_Filesystem structures are manipulated using the following meth‐
       ods.

       Tcl_FSRegister takes a pointer to a filesystem  structure  and  an  op‐
       tional  piece  of  data	to associated with that filesystem. On calling
       this function, Tcl will attach the filesystem  to  the  list  of	 known
       filesystems,  and it will become fully functional immediately. Tcl does
       not check if the same filesystem is registered multiple times  (and  in
       general that is not a good thing to do). TCL_OK will be returned.

       Tcl_FSUnregister	 removes  the given filesystem structure from the list
       of known filesystems, if it  is	known,	and  returns  TCL_OK.  If  the
       filesystem is not currently registered, TCL_ERROR is returned.

       Tcl_FSData  will	 return	 the  clientData  associated  with  the	 given
       filesystem, if that filesystem is registered. Otherwise it will	return
       NULL.

       Tcl_FSMountsChanged  is	used  to inform the Tcl's core that the set of
       mount  points  for  the	given  (already	 registered)  filesystem  have
       changed,	 and  that cached file representations may therefore no longer
       be correct.

   THE TCL_FILESYSTEM STRUCTURE
       The Tcl_Filesystem structure contains the following fields:

	      typedef struct Tcl_Filesystem {
		  const char *typeName;
		  int structureLength;
		  Tcl_FSVersion version;
		  Tcl_FSPathInFilesystemProc *pathInFilesystemProc;
		  Tcl_FSDupInternalRepProc *dupInternalRepProc;
		  Tcl_FSFreeInternalRepProc *freeInternalRepProc;
		  Tcl_FSInternalToNormalizedProc *internalToNormalizedProc;
		  Tcl_FSCreateInternalRepProc *createInternalRepProc;
		  Tcl_FSNormalizePathProc *normalizePathProc;
		  Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc;
		  Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc;
		  Tcl_FSStatProc *statProc;
		  Tcl_FSAccessProc *accessProc;
		  Tcl_FSOpenFileChannelProc *openFileChannelProc;
		  Tcl_FSMatchInDirectoryProc *matchInDirectoryProc;
		  Tcl_FSUtimeProc *utimeProc;
		  Tcl_FSLinkProc *linkProc;
		  Tcl_FSListVolumesProc *listVolumesProc;
		  Tcl_FSFileAttrStringsProc *fileAttrStringsProc;
		  Tcl_FSFileAttrsGetProc *fileAttrsGetProc;
		  Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
		  Tcl_FSCreateDirectoryProc *createDirectoryProc;
		  Tcl_FSRemoveDirectoryProc *removeDirectoryProc;
		  Tcl_FSDeleteFileProc *deleteFileProc;
		  Tcl_FSCopyFileProc *copyFileProc;
		  Tcl_FSRenameFileProc *renameFileProc;
		  Tcl_FSCopyDirectoryProc *copyDirectoryProc;
		  Tcl_FSLstatProc *lstatProc;
		  Tcl_FSLoadFileProc *loadFileProc;
		  Tcl_FSGetCwdProc *getCwdProc;
		  Tcl_FSChdirProc *chdirProc;
	      } Tcl_Filesystem;

       Except for the first three fields in this structure which contain  sim‐
       ple data elements, all entries contain addresses of functions called by
       the generic filesystem layer to perform the complete range of  filesys‐
       tem related actions.

       The  many  functions in this structure are broken down into three cate‐
       gories: infrastructure functions (almost all of which  must  be	imple‐
       mented), operational functions (which must be implemented if a complete
       filesystem is provided), and efficiency functions (which need  only  be
       implemented  if	they can be done so efficiently, or if they have side-
       effects which are required by the filesystem; Tcl  has  less  efficient
       emulations  it  can fall back on). It is important to note that, in the
       current version of Tcl, most of these fallbacks are only used to handle
       commands initiated in Tcl, not in C. What this means is, that if a file
       rename command is issued in Tcl, and the relevant filesystem(s) do  not
       implement  their Tcl_FSRenameFileProc, Tcl's core will instead fallback
       on a combination of other filesystem functions (it will use Tcl_FSCopy‐
       FileProc followed by Tcl_FSDeleteFileProc, and if Tcl_FSCopyFileProc is
       not implemented there is a further fallback). However, if  a  Tcl_FSRe‐
       nameFileProc command is issued at the C level, no such fallbacks occur.
       This is true except for the last four entries in the  filesystem	 table
       (lstat, load, getcwd and chdir) for which fallbacks do in fact occur at
       the C level.

       Any functions which take path names in Tcl_Obj form take those names in
       UTF-8  form.  The  filesystem infrastructure API is designed to support
       efficient, cached conversion of these UTF-8 paths to other native  rep‐
       resentations.

   EXAMPLE FILESYSTEM DEFINITION
       Here  is	 the filesystem lookup table used by the “vfs” extension which
       allows filesystem actions to be implemented in Tcl.

	      static Tcl_Filesystem vfsFilesystem = {
		  "tclvfs",
		  sizeof(Tcl_Filesystem),
		  TCL_FILESYSTEM_VERSION_1,
		  &VfsPathInFilesystem,
		  &VfsDupInternalRep,
		  &VfsFreeInternalRep,
		  /* No internal to normalized, since we don't create
		   * any pure 'internal' Tcl_Obj path representations */
		  NULL,
		  /* No create native rep function, since we don't use
		   * it and don't choose to support uses of
		   * Tcl_FSNewNativePath */
		  NULL,
		  /* Normalize path isn't needed - we assume paths only
		   * have one representation */
		  NULL,
		  &VfsFilesystemPathType,
		  &VfsFilesystemSeparator,
		  &VfsStat,
		  &VfsAccess,
		  &VfsOpenFileChannel,
		  &VfsMatchInDirectory,
		  &VfsUtime,
		  /* We choose not to support symbolic links inside our
		   * VFS's */
		  NULL,
		  &VfsListVolumes,
		  &VfsFileAttrStrings,
		  &VfsFileAttrsGet,
		  &VfsFileAttrsSet,
		  &VfsCreateDirectory,
		  &VfsRemoveDirectory,
		  &VfsDeleteFile,
		  /* No copy file; use the core fallback mechanism */
		  NULL,
		  /* No rename file; use the core fallback mechanism */
		  NULL,
		  /* No copy directory; use the core fallback mechanism */
		  NULL,
		  /* Core will use stat for lstat */
		  NULL,
		  /* No load; use the core fallback mechanism */
		  NULL,
		  /* We don't need a getcwd or chdir; the core's own
		   * internal value is suitable */
		  NULL,
		  NULL
	      };

FILESYSTEM INFRASTRUCTURE
       These fields contain basic information about the	 filesystem  structure
       and  addresses  of  functions  which are used to associate a particular
       filesystem with a file path, and deal with  the	internal  handling  of
       path  representations, for example copying and freeing such representa‐
       tions.

   TYPENAME
       The typeName field contains a null-terminated  string  that  identifies
       the type of the filesystem implemented, e.g.  “native”, “zip” or “vfs”.

   STRUCTURE LENGTH
       The    structureLength	 field	  is	generally    implemented    as
       sizeof(Tcl_Filesystem), and is there to allow easier  binary  backwards
       compatibility  if the size of the structure changes in a future Tcl re‐
       lease.

   VERSION
       The version field should be set to TCL_FILESYSTEM_VERSION_1.

   PATHINFILESYSTEMPROC
       The pathInFilesystemProc field contains the address of a function which
       is  called  to  determine  whether  a  given path value belongs to this
       filesystem or not. Tcl will only call the rest of the filesystem	 func‐
       tions  with a path for which this function has returned TCL_OK.	If the
       path does not belong, -1 should be returned (the behavior  of  Tcl  for
       any other return value is not defined). If TCL_OK is returned, then the
       optional clientDataPtr output parameter can be used to return an inter‐
       nal  (filesystem	 specific)  representation  of the path, which will be
       cached inside the path value, and may be retrieved efficiently  by  the
       other filesystem functions. Tcl will simultaneously cache the fact that
       this path belongs to this filesystem. Such caches are invalidated  when
       filesystem  structures are added or removed from Tcl's internal list of
       known filesystems.

	      typedef int Tcl_FSPathInFilesystemProc(
		      Tcl_Obj *pathPtr,
		      ClientData *clientDataPtr);

   DUPINTERNALREPPROC
       This function makes a copy of a path's internal representation, and  is
       called when Tcl needs to duplicate a path value. If NULL, Tcl will sim‐
       ply not copy the internal representation, which may then need to be re‐
       generated later.

	      typedef ClientData Tcl_FSDupInternalRepProc(
		      ClientData clientData);

   FREEINTERNALREPPROC
       Free  the internal representation. This must be implemented if internal
       representations need freeing (i.e. if some memory is allocated when  an
       internal representation is generated), but may otherwise be NULL.

	      typedef void Tcl_FSFreeInternalRepProc(
		      ClientData clientData);

   INTERNALTONORMALIZEDPROC
       Function	 to convert internal representation to a normalized path. Only
       required if the filesystem creates pure path values with no string/path
       representation.	The return value is a Tcl value whose string represen‐
       tation is the normalized path.

	      typedef Tcl_Obj *Tcl_FSInternalToNormalizedProc(
		      ClientData clientData);

   CREATEINTERNALREPPROC
       Function to take a path value, and calculate an internal representation
       for  it, and store that native representation in the value. May be NULL
       if paths have no	 internal  representation,  or	if  the	 Tcl_FSPathIn‐
       FilesystemProc for this filesystem always immediately creates an inter‐
       nal representation for paths it accepts.

	      typedef ClientData Tcl_FSCreateInternalRepProc(
		      Tcl_Obj *pathPtr);

   NORMALIZEPATHPROC
       Function to normalize a path. Should be implemented for all filesystems
       which can have multiple string representations for the same path value.
       In Tcl, every “path” must have a single unique “normalized” string rep‐
       resentation.  Depending	on  the filesystem, there may be more than one
       unnormalized string representation which refers to  that	 path  (e.g. a
       relative	 path,	a path with different character case if the filesystem
       is case insensitive, a path contain a reference	to  a  home  directory
       such  as	 “~”, a path containing symbolic links, etc). If the very last
       component in the path is a symbolic link, it should  not	 be  converted
       into  the  value	 it points to (but its case or other aspects should be
       made unique). All other path components should be converted  from  sym‐
       bolic  links. This one exception is required to agree with Tcl's seman‐
       tics with file delete, file rename, file	 copy  operating  on  symbolic
       links.	This  function may be called with nextCheckpoint either at the
       beginning of the path (i.e. zero), at the end of the path,  or  at  any
       intermediate  file  separator  in  the path. It will never point to any
       other arbitrary position in the path. In the last of  the  three	 valid
       cases,  the implementation can assume that the path up to and including
       the file separator is known and normalized.

	      typedef int Tcl_FSNormalizePathProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      int nextCheckpoint);

FILESYSTEM OPERATIONS
       The fields in this section of the structure contain addresses of	 func‐
       tions  which are called to carry out the basic filesystem operations. A
       filesystem which expects to be used with the complete standard Tcl com‐
       mand  set  must	implement all of these. If some of them are not imple‐
       mented, then certain Tcl commands may  fail  when  operating  on	 paths
       within  that  filesystem. However, in some instances this may be desir‐
       able (for example, a read-only filesystem should not implement the last
       four  functions, and a filesystem which does not support symbolic links
       need not implement the readlink function, etc.  The  Tcl	 core  expects
       filesystems to behave in this way).

   FILESYSTEMPATHTYPEPROC
       Function	 to  determine	the  type of a path in this filesystem. May be
       NULL, in which case no type information will be available to  users  of
       the filesystem. The “type” is used only for informational purposes, and
       should be returned as the string representation of the Tcl_Obj which is
       returned.  A typical return value might be “networked”, “zip” or “ftp”.
       The Tcl_Obj result is owned by the filesystem and so Tcl will increment
       the reference count of that value if it wishes to retain a reference to
       it.

	      typedef Tcl_Obj *Tcl_FSFilesystemPathTypeProc(
		      Tcl_Obj *pathPtr);

   FILESYSTEMSEPARATORPROC
       Function to return the  separator  character(s)	for  this  filesystem.
       This need only be implemented if the filesystem wishes to use a differ‐
       ent separator than the standard string “/”.  Amongst other uses, it  is
       returned	 by  the  file separator command. The return value should be a
       value with reference count of zero.

	      typedef Tcl_Obj *Tcl_FSFilesystemSeparatorProc(
		      Tcl_Obj *pathPtr);

   STATPROC
       Function to process a Tcl_FSStat call. Must be implemented for any rea‐
       sonable filesystem, since many Tcl level commands depend crucially upon
       it (e.g. file atime, file isdirectory, file size, glob).

	      typedef int Tcl_FSStatProc(
		      Tcl_Obj *pathPtr,
		      Tcl_StatBuf *statPtr);

       The Tcl_FSStatProc fills the stat structure  statPtr  with  information
       about the specified file. You do not need any access rights to the file
       to get this information but you need search rights to  all  directories
       named in the path leading to the file. The stat structure includes info
       regarding device, inode (always 0 on Windows),  privilege  mode,	 nlink
       (always	1 on Windows), user id (always 0 on Windows), group id (always
       0 on Windows), rdev (same as device  on	Windows),  size,  last	access
       time, last modification time, and last metadata change time.

       If the file represented by pathPtr exists, the Tcl_FSStatProc returns 0
       and the stat structure is filled with data. Otherwise, -1 is  returned,
       and no stat info is given.

   ACCESSPROC
       Function	 to  process  a Tcl_FSAccess call. Must be implemented for any
       reasonable filesystem, since many Tcl level commands  depend  crucially
       upon it (e.g. file exists, file readable).

	      typedef int Tcl_FSAccessProc(
		      Tcl_Obj *pathPtr,
		      int mode);

       The  Tcl_FSAccessProc  checks  whether  the process would be allowed to
       read, write or test for existence of the file (or other filesystem  ob‐
       ject)  whose  name  is in pathPtr. If the pathname refers to a symbolic
       link, then the permissions of the file referred by this	symbolic  link
       should be tested.

       On  success  (all  requested permissions granted), zero is returned. On
       error (at least one bit in mode asked for a permission that is  denied,
       or some other  error occurred), -1 is returned.

   OPENFILECHANNELPROC
       Function	 to  process a Tcl_FSOpenFileChannel call. Must be implemented
       for any reasonable filesystem, since any operations which require  open
       or  accessing  a	 file's contents will use it (e.g. open, encoding, and
       many Tk commands).

	      typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      int mode,
		      int permissions);

       The Tcl_FSOpenFileChannelProc opens a file specified by pathPtr and re‐
       turns  a channel handle that can be used to perform input and output on
       the file. This API is modeled after the fopen  procedure	 of  the  Unix
       standard	 I/O library. The syntax and meaning of all arguments is simi‐
       lar to those given in the Tcl open command when opening a  file,	 where
       the  mode  argument  is	a  combination	of  the	 POSIX flags O_RDONLY,
       O_WRONLY, etc. If an  error  occurs  while  opening  the	 channel,  the
       Tcl_FSOpenFileChannelProc  returns  NULL and records a POSIX error code
       that can be retrieved with Tcl_GetErrno.	 In  addition,	if  interp  is
       non-NULL,  the Tcl_FSOpenFileChannelProc leaves an error message in in‐
       terp's result after any error.

       The newly created channel must not be registered in the supplied inter‐
       preter by a Tcl_FSOpenFileChannelProc; that task is up to the caller of
       Tcl_FSOpenFileChannel (if necessary). If one of the standard  channels,
       stdin,  stdout or stderr was previously closed, the act of creating the
       new channel also assigns it as a replacement for the standard channel.

   MATCHINDIRECTORYPROC
       Function to process a Tcl_FSMatchInDirectory call. If not  implemented,
       then  glob  and	recursive  copy	 functionality	will be lacking in the
       filesystem (and this may impact commands like encoding names which  use
       glob functionality internally).

	      typedef int Tcl_FSMatchInDirectoryProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *resultPtr,
		      Tcl_Obj *pathPtr,
		      const char *pattern,
		      Tcl_GlobTypeData *types);

       The  function should return all files or directories (or other filesys‐
       tem objects) which match the given pattern and accord  with  the	 types
       specification  given.  There are two ways in which this function may be
       called. If pattern is NULL, then pathPtr is a full  path	 specification
       of a single file or directory which should be checked for existence and
       correct type. Otherwise, pathPtr is a directory, the contents of	 which
       the function should search for files or directories which have the cor‐
       rect type. In either case, pathPtr can be assumed to be	both  non-NULL
       and non-empty. It is not currently documented whether pathPtr will have
       a file separator at its end of not, so code should be flexible to  both
       possibilities.

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the matching process. Error messages are placed in  interp,
       unless interp in NULL in which case no error message need be generated;
       on a TCL_OK result, results should be  added  to	 the  resultPtr	 value
       given  (which  can  be  assumed	to  be a valid unshared Tcl list). The
       matches added to resultPtr should include  any  path  prefix  given  in
       pathPtr (this usually means they will be absolute path specifications).
       Note that if no matches are found, that simply leads to	an  empty  re‐
       sult;  errors  are only signaled for actual file or filesystem problems
       which may occur during the matching process.

       The Tcl_GlobTypeData structure passed in the types  parameter  contains
       the following fields:

	      typedef struct Tcl_GlobTypeData {
		  /* Corresponds to bcdpfls as in 'find -t' */
		  int type;
		  /* Corresponds to file permissions */
		  int perm;
		  /* Acceptable mac type */
		  Tcl_Obj *macType;
		  /* Acceptable mac creator */
		  Tcl_Obj *macCreator;
	      } Tcl_GlobTypeData;

       There are two specific cases which it is important to handle correctly,
       both when types is non-NULL. The two  cases  are	 when  types->types  &
       TCL_GLOB_TYPE_DIR  or  types->types & TCL_GLOB_TYPE_MOUNT are true (and
       in particular when the other flags are false). In the  first  of	 these
       cases,  the function must list the contained directories. Tcl uses this
       to implement recursive globbing, so it is critical that filesystems im‐
       plement	directory  matching  correctly.	 In the second of these cases,
       with TCL_GLOB_TYPE_MOUNT, the filesystem must  list  the	 mount	points
       which  lie within the given pathPtr (and in this case, pathPtr need not
       lie within the same filesystem - different to all other cases in	 which
       this  function  is  called).  Support for this is critical if Tcl is to
       have seamless transitions between from one filesystem to another.

   UTIMEPROC
       Function to process a Tcl_FSUtime call. Required to allow setting  (not
       reading)	 of  times  with  file	mtime, file atime and the open-r/open-
       w/fcopy implementation of file copy.

	      typedef int Tcl_FSUtimeProc(
		      Tcl_Obj *pathPtr,
		      struct utimbuf *tval);

       The access and modification times of  the  file	specified  by  pathPtr
       should be changed to the values given in the tval structure.

       The return value should be 0 on success and -1 on an error, as with the
       system utime.

   LINKPROC
       Function to process a Tcl_FSLink call. Should be	 implemented  only  if
       the filesystem supports links, and may otherwise be NULL.

	      typedef Tcl_Obj *Tcl_FSLinkProc(
		      Tcl_Obj *linkNamePtr,
		      Tcl_Obj *toPtr,
		      int linkAction);

       If toPtr is NULL, the function is being asked to read the contents of a
       link. The result is a Tcl_Obj specifying the contents of the link given
       by  linkNamePtr,	 or  NULL if the link could not be read. The result is
       owned by the caller (and should therefore have  its  ref	 count	incre‐
       mented before being returned). Any callers should call Tcl_DecrRefCount
       on this result when it is no longer needed.  If toPtr is not NULL,  the
       function	 should	 attempt  to  create  a link.  The result in this case
       should be toPtr if the link was successful and NULL otherwise. In  this
       case the result is not owned by the caller (i.e. no reference count ma‐
       nipulations on either  end  are	needed).  See  the  documentation  for
       Tcl_FSLink for the correct interpretation of the linkAction flags.

   LISTVOLUMESPROC
       Function	 to  list  any	filesystem  volumes  added by this filesystem.
       Should be implemented only if the filesystem adds volumes at  the  head
       of the filesystem, so that they can be returned by file volumes.

	      typedef Tcl_Obj *Tcl_FSListVolumesProc(void);

       The  result  should  be	a list of volumes added by this filesystem, or
       NULL (or an empty list) if no volumes are provided. The result value is
       considered  to  be  owned  by  the  filesystem (not by Tcl's core), but
       should be given a reference count for Tcl. Tcl will use the contents of
       the  list and then decrement that reference count. This allows filesys‐
       tems to choose whether they actually want to retain a “global list”  of
       volumes	or  not (if not, they generate the list on the fly and pass it
       to Tcl with a reference count of 1 and then forget about the  list,  if
       yes,  then  they	 simply	 increment the reference count of their global
       list and pass it to Tcl which will copy the contents and then decrement
       the count back to where it was).

       Therefore, Tcl considers return values from this proc to be read-only.

   FILEATTRSTRINGSPROC
       Function	 to  list  all	attribute  strings  which  are	valid for this
       filesystem. If not implemented the filesystem will not support the file
       attributes  command. This allows arbitrary additional information to be
       attached to files in the filesystem. If it is not implemented, there is
       no need to implement the get and set methods.

	      typedef const char *const *Tcl_FSFileAttrStringsProc(
		      Tcl_Obj *pathPtr,
		      Tcl_Obj **objPtrRef);

       The  called  function may either return an array of strings, or may in‐
       stead return NULL and place a Tcl list into the	given  objPtrRef.  Tcl
       will  take that list and first increment its reference count before us‐
       ing it.	On completion of that use, Tcl will  decrement	its  reference
       count.  Hence  if  the  list should be disposed of by Tcl when done, it
       should have a reference count of zero, and if the list  should  not  be
       disposed	 of,  the  filesystem  should ensure it returns a value with a
       reference count of at least one.

   FILEATTRSGETPROC
       Function to process a Tcl_FSFileAttrsGet call, used by file attributes.

	      typedef int Tcl_FSFileAttrsGetProc(
		      Tcl_Interp *interp,
		      int index,
		      Tcl_Obj *pathPtr,
		      Tcl_Obj **objPtrRef);

       Returns a standard Tcl return  code.  The  attribute  value  retrieved,
       which  corresponds  to the index'th element in the list returned by the
       Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if	TCL_OK
       was  returned)  and is likely to have a reference count of zero. Either
       way we must  either  store  it  somewhere  (e.g. the  Tcl  result),  or
       Incr/Decr its reference count to ensure it is properly freed.

   FILEATTRSSETPROC
       Function to process a Tcl_FSFileAttrsSet call, used by file attributes.
       If the filesystem is read-only, there is no need to implement this.

	      typedef int Tcl_FSFileAttrsSetProc(
		      Tcl_Interp *interp,
		      int index,
		      Tcl_Obj *pathPtr,
		      Tcl_Obj *objPtr);

       The attribute value of the index'th element in the list returned by the
       Tcl_FSFileAttrStringsProc should be set to the objPtr given.

   CREATEDIRECTORYPROC
       Function to process a Tcl_FSCreateDirectory call. Should be implemented
       unless the FS is read-only.

	      typedef int Tcl_FSCreateDirectoryProc(
		      Tcl_Obj *pathPtr);

       The return value is a standard Tcl result indicating whether  an	 error
       occurred	 in  the  process.  If successful, a new directory should have
       been added to the filesystem in the location specified by pathPtr.

   REMOVEDIRECTORYPROC
       Function to process a Tcl_FSRemoveDirectory call. Should be implemented
       unless the FS is read-only.

	      typedef int Tcl_FSRemoveDirectoryProc(
		      Tcl_Obj *pathPtr,
		      int recursive,
		      Tcl_Obj **errorPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the process. If  successful,	 the  directory	 specified  by
       pathPtr	should have been removed from the filesystem. If the recursive
       flag is given, then a non-empty directory should be deleted without er‐
       ror.  If	 this flag is not given, then and the directory is non-empty a
       POSIX “EEXIST” error should be signaled. If an error  does  occur,  the
       name  of	 the file or directory which caused the error should be placed
       in errorPtr.

   DELETEFILEPROC
       Function to process a Tcl_FSDeleteFile call. Should be implemented  un‐
       less the FS is read-only.

	      typedef int Tcl_FSDeleteFileProc(
		      Tcl_Obj *pathPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the process. If successful, the file specified  by  pathPtr
       should  have  been  removed  from  the  filesystem.  Note  that, if the
       filesystem supports symbolic links, Tcl will always call this  function
       and  not	 Tcl_FSRemoveDirectoryProc when needed to delete them (even if
       they are symbolic links to directories).

FILESYSTEM EFFICIENCY
       These functions need not be implemented for a particular filesystem be‐
       cause  the core has a fallback implementation available. See each indi‐
       vidual description for the consequences of leaving the field NULL.

   LSTATPROC
       Function to process a Tcl_FSLstat call. If not  implemented,  Tcl  will
       attempt	to  use	 the statProc defined above instead. Therefore it need
       only be implemented if a filesystem can differentiate between stat  and
       lstat calls.

	      typedef int Tcl_FSLstatProc(
		      Tcl_Obj *pathPtr,
		      Tcl_StatBuf *statPtr);

       The  behavior  of  this	function  is  very  similar  to	 that  of  the
       Tcl_FSStatProc defined above, except that if it is applied  to  a  sym‐
       bolic link, it returns information about the link, not about the target
       file.

   COPYFILEPROC
       Function to process a Tcl_FSCopyFile call. If not implemented Tcl  will
       fall  back  on open-r, open-w and fcopy as a copying mechanism.	There‐
       fore it need only be implemented if the filesystem can perform that ac‐
       tion more efficiently.

	      typedef int Tcl_FSCopyFileProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the copying process. Note that, destPathPtr is the name  of
       the  file  which	 should become the copy of srcPathPtr. It is never the
       name of a directory into which srcPathPtr  could	 be  copied  (i.e. the
       function is much simpler than the Tcl level file copy subcommand). Note
       that, if the filesystem supports symbolic links, Tcl will  always  call
       this  function and not copyDirectoryProc when needed to copy them (even
       if they are symbolic links to directories). Finally, if the  filesystem
       determines  it  cannot support the file copy action, calling Tcl_SetEr‐
       rno(EXDEV) and returning a non-TCL_OK result will tell Tcl to  use  its
       standard fallback mechanisms.

   RENAMEFILEPROC
       Function	 to  process  a Tcl_FSRenameFile call. If not implemented, Tcl
       will fall back on a copy and delete mechanism. Therefore it  need  only
       be  implemented	if  the	 filesystem can perform that action more effi‐
       ciently.

	      typedef int Tcl_FSRenameFileProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr);

       The return value is a standard Tcl result indicating whether  an	 error
       occurred	 in the renaming process. If the filesystem determines it can‐
       not support the file rename action, calling Tcl_SetErrno(EXDEV) and re‐
       turning	a non-TCL_OK result will tell Tcl to use its standard fallback
       mechanisms.

   COPYDIRECTORYPROC
       Function to process a Tcl_FSCopyDirectory call. If not implemented, Tcl
       will  fall  back on a recursive file mkdir, file copy mechanism. There‐
       fore it need only be implemented if the filesystem can perform that ac‐
       tion more efficiently.

	      typedef int Tcl_FSCopyDirectoryProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr,
		      Tcl_Obj **errorPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the copying process. If an error does occur,	 the  name  of
       the  file  or  directory which caused the error should be placed in er‐
       rorPtr. Note that, destPathPtr is the name of the directory-name	 which
       should  become  the mirror-image of srcPathPtr. It is not the name of a
       directory into which srcPathPtr should be copied (i.e. the function  is
       much  simpler than the Tcl level file copy subcommand). Finally, if the
       filesystem determines it cannot	support	 the  directory	 copy  action,
       calling Tcl_SetErrno(EXDEV) and returning a non-TCL_OK result will tell
       Tcl to use its standard fallback mechanisms.

   LOADFILEPROC
       Function to process a Tcl_FSLoadFile call. If not implemented, Tcl will
       fall back on a copy to native-temp followed by a Tcl_FSLoadFile on that
       temporary copy. Therefore it need only be implemented if the filesystem
       can  load  code	directly,  or  it  can be implemented simply to return
       TCL_ERROR to disable load functionality in this filesystem entirely.

	      typedef int Tcl_FSLoadFileProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      Tcl_LoadHandle *handlePtr,
		      Tcl_FSUnloadFileProc *unloadProcPtr);

       Returns a standard Tcl completion code. If an error  occurs,  an	 error
       message	is left in the interp's result. The function dynamically loads
       a binary code file into memory. On a  successful	 load,	the  handlePtr
       should  be filled with a token for the dynamically loaded file, and the
       unloadProcPtr should be filled in with the address of a procedure.  The
       unload  procedure  will	be called with the given Tcl_LoadHandle as its
       only parameter when Tcl needs to unload the file. For example, for  the
       native  filesystem,  the	 Tcl_LoadHandle	 returned is currently a token
       which can be used in the private TclpFindSymbol to access functions  in
       the  new	 code. Each filesystem is free to define the Tcl_LoadHandle as
       it requires. Finally, if the filesystem determines  it  cannot  support
       the  file load action, calling Tcl_SetErrno(EXDEV) and returning a non-
       TCL_OK result will tell Tcl to use its standard fallback mechanisms.

   UNLOADFILEPROC
       Function to unload a previously successfully loaded file. If  load  was
       implemented,  then  this	 should	 also  be implemented, if there is any
       cleanup action required.

	      typedef void Tcl_FSUnloadFileProc(
		      Tcl_LoadHandle loadHandle);

   GETCWDPROC
       Function to process a Tcl_FSGetCwd call. Most filesystems need not  im‐
       plement	this. It will usually only be called once, if getcwd is called
       before chdir. May be NULL.

	      typedef Tcl_Obj *Tcl_FSGetCwdProc(
		      Tcl_Interp *interp);

       If the filesystem supports a native notion of a current working	direc‐
       tory  (which  might  perhaps  change independent of Tcl), this function
       should return that cwd as the result, or NULL if the current  directory
       could  not  be determined (e.g. the user does not have appropriate per‐
       missions on the cwd directory). If NULL is returned, an	error  message
       is left in the interp's result.

   CHDIRPROC
       Function to process a Tcl_FSChdir call. If filesystems do not implement
       this, it will be emulated by a series of directory access checks.  Oth‐
       erwise,	virtual	 filesystems  which  do implement it need only respond
       with a positive return result if the pathPtr is a valid, accessible di‐
       rectory	in  their filesystem. They need not remember the result, since
       that will be automatically remembered for use  by  Tcl_FSGetCwd.	  Real
       filesystems  should carry out the correct action (i.e. call the correct
       system chdir API).

	      typedef int Tcl_FSChdirProc(
		      Tcl_Obj *pathPtr);

       The Tcl_FSChdirProc changes the applications current working  directory
       to  the value specified in pathPtr. The function returns -1 on error or
       0 on success.

SEE ALSO
       cd(n), file(n), filename(n), load(n), open(n), pwd(n),  source(n),  un‐
       load(n)

KEYWORDS
       stat, access, filesystem, vfs, virtual filesystem



Tcl				      8.4			 Filesystem(3)

Tcl_GetEncoding(3)	    Tcl Library Procedures	    Tcl_GetEncoding(3)



______________________________________________________________________________

NAME
       Tcl_GetEncoding,	  Tcl_FreeEncoding,   Tcl_GetEncodingFromObj,  Tcl_Ex‐
       ternalToUtfDString,    Tcl_ExternalToUtf,     Tcl_UtfToExternalDString,
       Tcl_UtfToExternal,  Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncod‐
       ingName,	  Tcl_SetSystemEncoding,   Tcl_GetEncodingNameFromEnvironment,
       Tcl_GetEncodingNames,   Tcl_CreateEncoding,  Tcl_GetEncodingSearchPath,
       Tcl_SetEncodingSearchPath,  Tcl_GetDefaultEncodingDir,  Tcl_SetDefault‐
       EncodingDir - procedures for creating and using encodings

SYNOPSIS
       #include <tcl.h>

       Tcl_Encoding
       Tcl_GetEncoding(interp, name)

       void
       Tcl_FreeEncoding(encoding)

       int
       Tcl_GetEncodingFromObj(interp, objPtr, encodingPtr)

       char *
       Tcl_ExternalToUtfDString(encoding, src, srcLen, dstPtr)

       char *
       Tcl_UtfToExternalDString(encoding, src, srcLen, dstPtr)

       int
       Tcl_ExternalToUtf(interp, encoding, src, srcLen, flags, statePtr,
			 dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr)

       int
       Tcl_UtfToExternal(interp, encoding, src, srcLen, flags, statePtr,
			 dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr)

       char *
       Tcl_WinTCharToUtf(tsrc, srcLen, dstPtr)

       TCHAR *
       Tcl_WinUtfToTChar(src, srcLen, dstPtr)

       const char *
       Tcl_GetEncodingName(encoding)

       int
       Tcl_SetSystemEncoding(interp, name)

       const char *
       Tcl_GetEncodingNameFromEnvironment(bufPtr)

       void
       Tcl_GetEncodingNames(interp)

       Tcl_Encoding
       Tcl_CreateEncoding(typePtr)

       Tcl_Obj *
       Tcl_GetEncodingSearchPath()

       int
       Tcl_SetEncodingSearchPath(searchPath)

       const char *
       Tcl_GetDefaultEncodingDir(void)

       void
       Tcl_SetDefaultEncodingDir(path)

ARGUMENTS
       Tcl_Interp *interp (in)				 Interpreter   to  use
							 for error  reporting,
							 or  NULL  if no error
							 reporting is desired.

       const char *name (in)				 Name of  encoding  to
							 load.

       Tcl_Encoding encoding (in)			 The	encoding    to
							 query, free,  or  use
							 for  converting text.
							 If encoding is	 NULL,
							 the   current	system
							 encoding is used.

       Tcl_Obj *objPtr (in)				 Name of  encoding  to
							 get token for.

       Tcl_Encoding *encodingPtr (out)			 Points	  to   storage
							 where encoding	 token
							 is to be written.

       const char *src (in)				 For	the    Tcl_Ex‐
							 ternalToUtf	 func‐
							 tions,	 an  array  of
							 bytes in  the	speci‐
							 fied	encoding  that
							 are to	 be  converted
							 to  UTF-8.   For  the
							 Tcl_UtfToExternal and
							 Tcl_WinUtfToTChar
							 functions,  an	 array
							 of  UTF-8  characters
							 to  be	 converted  to
							 the  specified encod‐
							 ing.

       const TCHAR *tsrc (in)				 An array  of  Windows
							 TCHAR	characters  to
							 convert to UTF-8.

       int srcLen (in)					 Length of src or tsrc
							 in   bytes.   If  the
							 length	 is  negative,
							 the encoding-specific
							 length of the	string
							 is used.

       Tcl_DString *dstPtr (out)			 Pointer  to an unini‐
							 tialized   or	  free
							 Tcl_DString  in which
							 the converted	result
							 will be stored.

       int flags (in)					 Various flag bits OR-
							 ed together.  TCL_EN‐
							 CODING_START	signi‐
							 fies that the	source
							 buffer	 is  the first
							 block	in  a  (poten‐
							 tially	  multi-block)
							 input stream, telling
							 the  conversion  rou‐
							 tine to reset	to  an
							 initial   state   and
							 perform any  initial‐
							 ization that needs to
							 occur	 before	   the
							 first	byte  is  con‐
							 verted.    TCL_ENCOD‐
							 ING_END     signifies
							 that the source  buf‐
							 fer is the last block
							 in   a	  (potentially
							 multi-block)	 input
							 stream,  telling  the
							 conversion routine to
							 perform any finaliza‐
							 tion  that  needs  to
							 occur after the  last
							 byte is converted and
							 then to reset	to  an
							 initial	state.
							 TCL_ENCODING_STOPON‐
							 ERROR	signifies that
							 the  conversion  rou‐
							 tine	should	return
							 immediately	  upon
							 reading    a	source
							 character  that  does
							 not exist in the tar‐
							 get encoding;	other‐
							 wise  a default fall‐
							 back  character  will
							 automatically be sub‐
							 stituted.

       Tcl_EncodingState *statePtr (in/out)		 Used when  converting
							 a  (generally long or
							 indefinite    length)
							 byte	stream	 in  a
							 piece-by-piece	 fash‐
							 ion.	The conversion
							 routine  stores   its
							 current    state   in
							 *statePtr  after  src
							 (the  buffer contain‐
							 ing	the    current
							 piece)	 has been con‐
							 verted;  that	 state
							 information  must  be
							 passed back when con‐
							 verting    the	  next
							 piece of  the	stream
							 so   the   conversion
							 routine  knows	  what
							 state	it was in when
							 it left  off  at  the
							 end   of   the	  last
							 piece.	 May be	 NULL,
							 in   which  case  the
							 value	specified  for
							 flags	is ignored and
							 the source buffer  is
							 assumed   to  contain
							 the  complete	string
							 to convert.

       char *dst (out)					 Buffer	 in  which the
							 converted result will
							 be  stored.   No more
							 than	dstLen	 bytes
							 will	be  stored  in
							 dst.

       int dstLen (in)					 The maximum length of
							 the output buffer dst
							 in bytes.

       int *srcReadPtr (out)				 Filled with the  num‐
							 ber of bytes from src
							 that  were   actually
							 converted.   This may
							 be  less   than   the
							 original	source
							 length if there was a
							 problem    converting
							 some  source  charac‐
							 ters.	May be NULL.

       int *dstWrotePtr (out)				 Filled	 with the num‐
							 ber  of  bytes	  that
							 were  actually stored
							 in the output	buffer
							 as  a	result	of the
							 conversion.   May  be
							 NULL.

       int *dstCharsPtr (out)				 Filled	 with the num‐
							 ber   of   characters
							 that	correspond  to
							 the number  of	 bytes
							 stored	 in the output
							 buffer.  May be NULL.

       Tcl_DString *bufPtr (out)			 Storage for the  pre‐
							 scribed system encod‐
							 ing name.

       const Tcl_EncodingType *typePtr (in)		 Structure  that   de‐
							 fines	a  new type of
							 encoding.

       Tcl_Obj *searchPath (in)				 List  of   filesystem
							 directories  in which
							 to search for	encod‐
							 ing data files.

       const char *path (in)				 A  path  to the loca‐
							 tion of the  encoding
							 file.
______________________________________________________________________________

INTRODUCTION
       These routines convert between Tcl's internal character representation,
       UTF-8, and character representations used by various operating  systems
       or  file systems, such as Unicode, ASCII, or Shift-JIS.	When operating
       on strings, such as such as obtaining the names of files or  displaying
       characters  using  international	 fonts, the strings must be translated
       into one or possibly multiple formats that the various system calls can
       use.  For instance, on a Japanese Unix workstation, a user might obtain
       a filename represented in the EUC-JP file encoding and  then  translate
       the  characters	to  the jisx0208 font encoding in order to display the
       filename in a Tk widget.	 The purpose of the  encoding  package	is  to
       help  bridge the translation gap.  UTF-8 provides an intermediate stag‐
       ing ground for all the various encodings.  In the example  above,  text
       would  be translated into UTF-8 from whatever file encoding the operat‐
       ing system is using.  Then it would be translated from UTF-8 into what‐
       ever font encoding the display routines require.

       Some  basic  encodings are compiled into Tcl.  Others can be defined by
       the user or dynamically loaded from encoding files in a	platform-inde‐
       pendent manner.

DESCRIPTION
       Tcl_GetEncoding	finds  an encoding given its name.  The name may refer
       to a built-in Tcl encoding, a user-defined encoding registered by call‐
       ing  Tcl_CreateEncoding,	 or a dynamically-loadable encoding file.  The
       return value is a token that represents the encoding and can be used in
       subsequent calls to procedures such as Tcl_GetEncodingName, Tcl_FreeEn‐
       coding, and Tcl_UtfToExternal.  If the name did not refer to any	 known
       or loadable encoding, NULL is returned and an error message is returned
       in interp.

       The encoding package maintains a database of all encodings currently in
       use.   The first time name is seen, Tcl_GetEncoding returns an encoding
       with a reference count of 1.  If the same  name	is  requested  further
       times,  then the reference count for that encoding is incremented with‐
       out the overhead of allocating a new encoding and  all  its  associated
       data structures.

       When an encoding is no longer needed, Tcl_FreeEncoding should be called
       to release it.  When an encoding is no longer in use anywhere (i.e., it
       has  been  freed	 as many times as it has been gotten) Tcl_FreeEncoding
       will release all storage the encoding was using and delete it from  the
       database.

       Tcl_GetEncodingFromObj treats the string representation of objPtr as an
       encoding name, and finds an encoding with that name, just as Tcl_GetEn‐
       coding  does. When an encoding is found, it is cached within the objPtr
       value for future reference, the Tcl_Encoding token is  written  to  the
       storage pointed to by encodingPtr, and the value TCL_OK is returned. If
       no such encoding is found, the value  TCL_ERROR	is  returned,  and  no
       writing	to *encodingPtr takes place. Just as with Tcl_GetEncoding, the
       caller should call Tcl_FreeEncoding on  the  resulting  encoding	 token
       when that token will no longer be used.

       Tcl_ExternalToUtfDString	 converts  a source buffer src from the speci‐
       fied encoding into UTF-8.  The converted bytes are  stored  in  dstPtr,
       which  is  then	null-terminated.   The	caller	should eventually call
       Tcl_DStringFree to free any information stored in  dstPtr.   When  con‐
       verting, if any of the characters in the source buffer cannot be repre‐
       sented in the target encoding, a default	 fallback  character  will  be
       used.   The  return  value  is  a  pointer  to  the value stored in the
       DString.

       Tcl_ExternalToUtf converts a source buffer src from the	specified  en‐
       coding  into  UTF-8.   Up to srcLen bytes are converted from the source
       buffer and up to dstLen converted bytes are  stored  in	dst.   In  all
       cases,  *srcReadPtr  is	filled with the number of bytes that were suc‐
       cessfully converted from src and *dstWrotePtr is filled with the corre‐
       sponding	 number of bytes that were stored in dst.  The return value is
       one of the following:

	      TCL_OK			   All bytes of src were converted.

	      TCL_CONVERT_NOSPACE	   The	destination  buffer  was   not
					   large  enough  for  all of the con‐
					   verted data; as many characters  as
					   could fit were converted though.

	      TCL_CONVERT_MULTIBYTE	   The	last  few  bytes in the source
					   buffer  were	 the  beginning	 of  a
					   multibyte  sequence, but more bytes
					   were needed to  complete  this  se‐
					   quence.   A	subsequent call to the
					   conversion routine  should  pass  a
					   buffer  containing  the unconverted
					   bytes that  remained	 in  src  plus
					   some	 further bytes from the source
					   stream to properly convert the for‐
					   merly split-up multibyte sequence.

	      TCL_CONVERT_SYNTAX	   The	source buffer contained an in‐
					   valid character sequence.  This may
					   occur  if the input stream has been
					   damaged or if  the  input  encoding
					   method was misidentified.

	      TCL_CONVERT_UNKNOWN	   The source buffer contained a char‐
					   acter that could not be represented
					   in  the target encoding and TCL_EN‐
					   CODING_STOPONERROR was specified.

       Tcl_UtfToExternalDString converts a source buffer src from  UTF-8  into
       the  specified  encoding.   The	converted  bytes are stored in dstPtr,
       which is then terminated with the appropriate  encoding-specific	 null.
       The  caller should eventually call Tcl_DStringFree to free any informa‐
       tion stored in dstPtr.  When converting, if any of  the	characters  in
       the  source  buffer cannot be represented in the target encoding, a de‐
       fault fallback character will be used.  The return value is  a  pointer
       to the value stored in the DString.

       Tcl_UtfToExternal  converts  a  source  buffer  src from UTF-8 into the
       specified encoding.  Up to srcLen bytes are converted from  the	source
       buffer  and  up	to  dstLen  converted bytes are stored in dst.	In all
       cases, *srcReadPtr is filled with the number of bytes  that  were  suc‐
       cessfully converted from src and *dstWrotePtr is filled with the corre‐
       sponding number of bytes that were stored in dst.   The	return	values
       are the same as the return values for Tcl_ExternalToUtf.

       Tcl_WinUtfToTChar  and  Tcl_WinTCharToUtf  are Windows-only convenience
       functions for converting between UTF-8 and Windows strings based on the
       TCHAR type which is by convention a Unicode character on Windows NT.

       Tcl_GetEncodingName  is	roughly the inverse of Tcl_GetEncoding.	 Given
       an encoding, the return value is the name argument  that	 was  used  to
       create  the  encoding.	The  string returned by Tcl_GetEncodingName is
       only guaranteed to persist until the encoding is deleted.   The	caller
       must not modify this string.

       Tcl_SetSystemEncoding  sets  the	 default  encoding that should be used
       whenever the user passes a NULL value for the encoding argument to  any
       of  the other encoding functions.  If name is NULL, the system encoding
       is reset to the default system encoding, binary.	 If the name  did  not
       refer  to  any known or loadable encoding, TCL_ERROR is returned and an
       error message is left in interp.	 Otherwise, this procedure  increments
       the  reference  count of the new system encoding, decrements the refer‐
       ence count of the old system encoding, and returns TCL_OK.

       Tcl_GetEncodingNameFromEnvironment provides a means for the Tcl library
       to report the encoding name it believes to be the correct one to use as
       the system encoding, based on system calls and examination of the envi‐
       ronment	suitable for the platform.  It accepts bufPtr, a pointer to an
       uninitialized or freed Tcl_DString and writes the encoding name to  it.
       The Tcl_DStringValue is returned.

       Tcl_GetEncodingNames sets the interp result to a list consisting of the
       names of all the encodings that are currently defined or can be dynami‐
       cally  loaded, searching the encoding path specified by Tcl_SetDefault‐
       EncodingDir.  This procedure does not ensure that the dynamically-load‐
       able encoding files contain valid data, but merely that they exist.

       Tcl_CreateEncoding  defines  a  new encoding and registers the C proce‐
       dures that are called back to convert between the encoding  and	UTF-8.
       Encodings  created  by Tcl_CreateEncoding are thereafter visible in the
       database used by Tcl_GetEncoding.  Just	as  with  the  Tcl_GetEncoding
       procedure, the return value is a token that represents the encoding and
       can be used in subsequent calls to other encoding functions.   Tcl_Cre‐
       ateEncoding  returns an encoding with a reference count of 1. If an en‐
       coding with the specified name already exists, then its	entry  in  the
       database	 is  replaced with the new encoding; the token for the old en‐
       coding will remain valid and continue to behave as before, but users of
       the new token will now call the new encoding procedures.

       The  typePtr  argument to Tcl_CreateEncoding contains information about
       the name of the encoding and the procedures that will be called to con‐
       vert between this encoding and UTF-8.  It is defined as follows:

	      typedef struct Tcl_EncodingType {
		  const char *encodingName;
		  Tcl_EncodingConvertProc *toUtfProc;
		  Tcl_EncodingConvertProc *fromUtfProc;
		  Tcl_EncodingFreeProc *freeProc;
		  ClientData clientData;
		  int nullSize;
	      } Tcl_EncodingType;

       The  encodingName  provides a string name for the encoding, by which it
       can be referred in  other  procedures  such  as	Tcl_GetEncoding.   The
       toUtfProc refers to a callback procedure to invoke to convert text from
       this encoding into UTF-8.  The fromUtfProc refers to a callback	proce‐
       dure  to	 invoke	 to  convert  text from UTF-8 into this encoding.  The
       freeProc refers to a callback procedure to invoke when this encoding is
       deleted.	  The  freeProc field may be NULL.  The clientData contains an
       arbitrary one-word value passed to toUtfProc, fromUtfProc, and freeProc
       whenever	 they  are  called.   Typically,  this	is a pointer to a data
       structure containing encoding-specific information that can be used  by
       the callback procedures.	 For instance, two very similar encodings such
       as ascii and macRoman may use the same callback procedure, but use dif‐
       ferent  values  of  clientData  to  control its behavior.  The nullSize
       specifies the number of zero bytes that signify end-of-string  in  this
       encoding.   It  must be 1 (for single-byte or multi-byte encodings like
       ASCII or Shift-JIS) or 2	 (for  double-byte  encodings  like  Unicode).
       Constant-sized  encodings  with	3 or more bytes per character (such as
       CNS11643) are not accepted.

       The callback procedures toUtfProc and fromUtfProc should match the type
       Tcl_EncodingConvertProc:

	      typedef int Tcl_EncodingConvertProc(
		      ClientData clientData,
		      const char *src,
		      int srcLen,
		      int flags,
		      Tcl_EncodingState *statePtr,
		      char *dst,
		      int dstLen,
		      int *srcReadPtr,
		      int *dstWrotePtr,
		      int *dstCharsPtr);

       The  toUtfProc  and  fromUtfProc	 procedures  are called by the Tcl_Ex‐
       ternalToUtf or Tcl_UtfToExternal family of functions to perform the ac‐
       tual  conversion.   The clientData parameter to these procedures is the
       same as the clientData field specified to Tcl_CreateEncoding  when  the
       encoding	 was  created.	The remaining arguments to the callback proce‐
       dures are the same as the arguments, documented at the top, to  Tcl_Ex‐
       ternalToUtf  or	Tcl_UtfToExternal,  with the following exceptions.  If
       the srcLen argument to one of those high-level functions	 is  negative,
       the  value passed to the callback procedure will be the appropriate en‐
       coding-specific string length of src.  If any of the  srcReadPtr,  dst‐
       WrotePtr,  or  dstCharsPtr arguments to one of the high-level functions
       is NULL, the corresponding value passed to the callback procedure  will
       be a non-NULL location.

       The  callback  procedure	 freeProc,  if non-NULL, should match the type
       Tcl_EncodingFreeProc:

	      typedef void Tcl_EncodingFreeProc(
		      ClientData clientData);

       This freeProc function is called when the  encoding  is	deleted.   The
       clientData  parameter  is the same as the clientData field specified to
       Tcl_CreateEncoding when the encoding was created.

       Tcl_GetEncodingSearchPath and Tcl_SetEncodingSearchPath are  called  to
       access and set the list of filesystem directories searched for encoding
       data files.

       The value returned by Tcl_GetEncodingSearchPath is the value stored  by
       the  last successful call to Tcl_SetEncodingSearchPath.	If no calls to
       Tcl_SetEncodingSearchPath have occurred, Tcl will  compute  an  initial
       value  based on the environment.	 There is one encoding search path for
       the entire process, shared by all threads in the process.

       Tcl_SetEncodingSearchPath stores searchPath and returns TCL_OK,	unless
       searchPath  is  not  a valid Tcl list, which causes TCL_ERROR to be re‐
       turned.	The elements of searchPath are not verified as existing	 read‐
       able  filesystem	 directories.	When searching for encoding data files
       takes place, and non-existent or non-readable filesystem directories on
       the searchPath are silently ignored.

       Tcl_GetDefaultEncodingDir  and  Tcl_SetDefaultEncodingDir  are obsolete
       interfaces best replaced with calls  to	Tcl_GetEncodingSearchPath  and
       Tcl_SetEncodingSearchPath.  They are called to access and set the first
       element of the searchPath list.	Since Tcl searches searchPath for  en‐
       coding data files in list order, these routines establish the “default”
       directory in which to find encoding data files.

ENCODING FILES
       Space would prohibit precompiling into Tcl every possible encoding  al‐
       gorithm,	 so  many encodings are stored on disk as dynamically-loadable
       encoding files.	This behavior also allows the  user  to	 create	 addi‐
       tional  encoding	 files	that  can  be loaded using the same mechanism.
       These encoding files contain information about the tables and/or escape
       sequences  used	to  map between an external encoding and Unicode.  The
       external encoding may consist of single-byte,  multi-byte,  or  double-
       byte characters.

       Each  dynamically-loadable encoding is represented as a text file.  The
       initial line of the file, beginning with a “#”  symbol,	is  a  comment
       that  provides a human-readable description of the file.	 The next line
       identifies the type of encoding file.  It can be one of	the  following
       letters:

       [1] S  A	 single-byte  encoding, where one character is always one byte
	      long in the encoding.  An example is iso8859-1, used by many Eu‐
	      ropean languages.

       [2] D  A	 double-byte encoding, where one character is always two bytes
	      long in the encoding.  An example	 is  big5,  used  for  Chinese
	      text.

       [3] M  A	 multi-byte encoding, where one character may be either one or
	      two bytes long.  Certain bytes are lead bytes,  indicating  that
	      another  byte must follow and that together the two bytes repre‐
	      sent one character.  Other bytes are not lead bytes  and	repre‐
	      sent  themselves.	 An example is shiftjis, used by many Japanese
	      computers.

       [4] E  An escape-sequence encoding, specifying that  certain  sequences
	      of bytes do not represent characters, but commands that describe
	      how following bytes should be interpreted.

       The rest of the lines in the file depend on the type.

       Cases [1], [2], and [3] are collectively referred to as table-based en‐
       coding files.  The lines in a table-based encoding file are in the same
       format as this example taken from the shiftjis encoding	(this  is  not
       the complete file):

	      # Encoding file: shiftjis, multi-byte
	      M
	      003F 0 40
	      00
	      0000000100020003000400050006000700080009000A000B000C000D000E000F
	      0010001100120013001400150016001700180019001A001B001C001D001E001F
	      0020002100220023002400250026002700280029002A002B002C002D002E002F
	      0030003100320033003400350036003700380039003A003B003C003D003E003F
	      0040004100420043004400450046004700480049004A004B004C004D004E004F
	      0050005100520053005400550056005700580059005A005B005C005D005E005F
	      0060006100620063006400650066006700680069006A006B006C006D006E006F
	      0070007100720073007400750076007700780079007A007B007C007D203E007F
	      0080000000000000000000000000000000000000000000000000000000000000
	      0000000000000000000000000000000000000000000000000000000000000000
	      0000FF61FF62FF63FF64FF65FF66FF67FF68FF69FF6AFF6BFF6CFF6DFF6EFF6F
	      FF70FF71FF72FF73FF74FF75FF76FF77FF78FF79FF7AFF7BFF7CFF7DFF7EFF7F
	      FF80FF81FF82FF83FF84FF85FF86FF87FF88FF89FF8AFF8BFF8CFF8DFF8EFF8F
	      FF90FF91FF92FF93FF94FF95FF96FF97FF98FF99FF9AFF9BFF9CFF9DFF9EFF9F
	      0000000000000000000000000000000000000000000000000000000000000000
	      0000000000000000000000000000000000000000000000000000000000000000
	      81
	      0000000000000000000000000000000000000000000000000000000000000000
	      0000000000000000000000000000000000000000000000000000000000000000
	      0000000000000000000000000000000000000000000000000000000000000000
	      0000000000000000000000000000000000000000000000000000000000000000
	      300030013002FF0CFF0E30FBFF1AFF1BFF1FFF01309B309C00B4FF4000A8FF3E
	      FFE3FF3F30FD30FE309D309E30034EDD30053006300730FC20152010FF0F005C
	      301C2016FF5C2026202520182019201C201DFF08FF0930143015FF3BFF3DFF5B
	      FF5D30083009300A300B300C300D300E300F30103011FF0B221200B100D70000
	      00F7FF1D2260FF1CFF1E22662267221E22342642264000B0203220332103FFE5
	      FF0400A200A3FF05FF03FF06FF0AFF2000A72606260525CB25CF25CE25C725C6
	      25A125A025B325B225BD25BC203B301221922190219121933013000000000000
	      000000000000000000000000000000002208220B2286228722822283222A2229
	      000000000000000000000000000000002227222800AC21D221D4220022030000
	      0000000000000000000000000000000000000000222022A52312220222072261
	      2252226A226B221A223D221D2235222B222C0000000000000000000000000000
	      212B2030266F266D266A2020202100B6000000000000000025EF000000000000

       The  third  line of the file is three numbers.  The first number is the
       fallback character (in base 16) to use when converting  from  UTF-8  to
       this  encoding.	 The  second number is a 1 if this file represents the
       encoding for a symbol font, or 0 otherwise.  The last number  (in  base
       10) is how many pages of data follow.

       Subsequent  lines  in  the example above are pages that describe how to
       map from the encoding into 2-byte Unicode.  The first line  in  a  page
       identifies  the page number.  Following it are 256 double-byte numbers,
       arranged as 16 rows of 16 numbers.  Given a character in the  encoding,
       the  high  byte of that character is used to select which page, and the
       low byte of that character is used as an index to  select  one  of  the
       double-byte  numbers in that page - the value obtained being the corre‐
       sponding Unicode character.  By examination of the example  above,  one
       can see that the characters 0x7E and 0x8163 in shiftjis map to 203E and
       2026 in Unicode, respectively.

       Following the first page will be all the other pages, each in the  same
       format  as  the	first: one number identifying the page followed by 256
       double-byte Unicode characters.	If a character in the encoding maps to
       the  Unicode character 0000, it means that the character does not actu‐
       ally exist.  If all characters on a page would map to 0000,  that  page
       can be omitted.

       Case  [4]  is  the escape-sequence encoding file.  The lines in an this
       type of file are in the same format as  this  example  taken  from  the
       iso2022-jp encoding:

	      # Encoding file: iso2022-jp, escape-driven
	      E
	      init	     {}
	      final	     {}
	      iso8859-1	     \x1b(B
	      jis0201	     \x1b(J
	      jis0208	     \x1b$@
	      jis0208	     \x1b$B
	      jis0212	     \x1b$(D
	      gb2312	     \x1b$A
	      ksc5601	     \x1b$(C

       In  the file, the first column represents an option and the second col‐
       umn is the associated value.  init is a string to emit or expect before
       the  first  character  is converted, while final is a string to emit or
       expect after the last character.	 All other options are names of table-
       based encodings; the associated value is the escape-sequence that marks
       that encoding.  Tcl syntax is used for the values; in the  above	 exam‐
       ple,  for  instance, “{}” represents the empty string and “\x1b” repre‐
       sents character 27.

       When Tcl_GetEncoding encounters an encoding  name  that	has  not  been
       loaded,	it  attempts to load an encoding file called name.enc from the
       encoding subdirectory of each  directory	 that  Tcl  searches  for  its
       script  library.	 If the encoding file exists, but is malformed, an er‐
       ror message will be left in interp.

KEYWORDS
       utf, encoding, convert



Tcl				      8.1		    Tcl_GetEncoding(3)

Tcl_BooleanObj(3)	    Tcl Library Procedures	     Tcl_BooleanObj(3)



______________________________________________________________________________

NAME
       Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj - store/re‐
       trieve boolean value in a Tcl_Obj

SYNOPSIS
       #include <tcl.h>

       Tcl_Obj *
       Tcl_NewBooleanObj(intValue)

       Tcl_SetBooleanObj(objPtr, intValue)

       int
       Tcl_GetBooleanFromObj(interp, objPtr, intPtr)

ARGUMENTS
       int intValue (in)		 Integer value to be stored as a bool‐
					 ean 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
					 boolean value.

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

       int *intPtr (out)		 Points to place where Tcl_GetBoolean‐
					 FromObj  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 intValue 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 int‐
       Value 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 intValue.   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  intValue
       into *objPtr implies the freeing of any former 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 ad‐
       dress given by intPtr.  If objPtr holds any value recognized as a  num‐
       ber  by	Tcl,  then if that value is zero a 0 is written at the address
       given by intPtr and if that value is non-zero a 1 is written at the ad‐
       dress  given  by	 intPtr.  In all cases where a value is written at the
       address given by intPtr, Tcl_GetBooleanFromObj returns TCL_OK.  If  the
       value of objPtr does not meet any of the conditions above, then TCL_ER‐
       ROR is returned and an error message is left in the  interpreter's  re‐
       sult  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 effi‐
       ciently.

       Note that the routines Tcl_GetBooleanFromObj and Tcl_GetBoolean are not
       functional equivalents.	The set of values for which Tcl_GetBooleanFro‐
       mObj 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, value



Tcl				      8.5		     Tcl_BooleanObj(3)

Tcl_TraceVar(3)		    Tcl Library Procedures	       Tcl_TraceVar(3)



______________________________________________________________________________

NAME
       Tcl_TraceVar,  Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_Var‐
       TraceInfo, Tcl_VarTraceInfo2 - monitor accesses to a variable

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_TraceVar(interp, varName, flags, proc, clientData)

       int
       Tcl_TraceVar2(interp, name1, name2, flags, proc, clientData)

       Tcl_UntraceVar(interp, varName, flags, proc, clientData)

       Tcl_UntraceVar2(interp, name1, name2, flags, proc, clientData)

       ClientData
       Tcl_VarTraceInfo(interp, varName, flags, proc, prevClientData)

       ClientData
       Tcl_VarTraceInfo2(interp, name1, name2, flags, proc, prevClientData)

ARGUMENTS
       Tcl_Interp *interp (in)			     Interpreter    containing
						     variable.

       const char *varName (in)			     Name  of  variable.   May
						     refer to a	 scalar	 vari‐
						     able,  to	an array vari‐
						     able with no index, or to
						     an	 array variable with a
						     parenthesized index.

       int flags (in)				     OR-ed combination of  the
						     values   TCL_TRACE_READS,
						     TCL_TRACE_WRITES,
						     TCL_TRACE_UNSETS,
						     TCL_TRACE_ARRAY,
						     TCL_GLOBAL_ONLY,
						     TCL_NAMESPACE_ONLY,
						     TCL_TRACE_RESULT_DYNAMIC
						     and  TCL_TRACE_RESULT_OB‐
						     JECT.   Not all flags are
						     used by  all  procedures.
						     See below for more infor‐
						     mation.

       Tcl_VarTraceProc *proc (in)		     Procedure to invoke when‐
						     ever  one	of  the traced
						     operations occurs.

       ClientData clientData (in)		     Arbitrary one-word	 value
						     to pass to proc.

       const char *name1 (in)			     Name  of  scalar or array
						     variable  (without	 array
						     index).

       const char *name2 (in)			     For a trace on an element
						     of an  array,  gives  the
						     index   of	 the  element.
						     For  traces   on	scalar
						     variables or on whole ar‐
						     rays, is NULL.

       ClientData prevClientData (in)		     If non-NULL,  gives  last
						     value     returned	    by
						     Tcl_VarTraceInfo	    or
						     Tcl_VarTraceInfo2,	    so
						     this call will return in‐
						     formation	  about	  next
						     trace.   If  NULL,	  this
						     call will return informa‐
						     tion about first trace.
______________________________________________________________________________

DESCRIPTION
       Tcl_TraceVar allows a C procedure to monitor and control	 access	 to  a
       Tcl  variable, so that the C procedure is invoked whenever the variable
       is read or written or unset.  If the trace is created successfully then
       Tcl_TraceVar returns TCL_OK.  If an error occurred (e.g. varName speci‐
       fies an element of an array, but the actual variable is not  an	array)
       then  TCL_ERROR	is returned and an error message is left in the inter‐
       preter's result.

       The flags argument to Tcl_TraceVar indicates when the  trace  procedure
       is to be invoked and provides information for setting up the trace.  It
       consists of an OR-ed combination of any of the following values:

       TCL_GLOBAL_ONLY
	      Normally, the variable will be looked up at the current level of
	      procedure	 call;	 if  this bit is set then the variable will be
	      looked up at global level, ignoring any active procedures.

       TCL_NAMESPACE_ONLY
	      Normally, the variable will be looked up at the current level of
	      procedure	 call;	 if  this bit is set then the variable will be
	      looked up in the current namespace, ignoring any	active	proce‐
	      dures.

       TCL_TRACE_READS
	      Invoke proc whenever an attempt is made to read the variable.

       TCL_TRACE_WRITES
	      Invoke proc whenever an attempt is made to modify the variable.

       TCL_TRACE_UNSETS
	      Invoke  proc  whenever the variable is unset.  A variable may be
	      unset either explicitly by an unset command, or implicitly  when
	      a	 procedure  returns (its local variables are automatically un‐
	      set) or when the interpreter is deleted (all variables are auto‐
	      matically unset).

       TCL_TRACE_ARRAY
	      Invoke  proc  whenever the array command is invoked.  This gives
	      the trace procedure a chance to update the  array	 before	 array
	      names  or	 array get is called.  Note that this is called before
	      an array set, but that will trigger write traces.

       TCL_TRACE_RESULT_DYNAMIC
	      The result of invoking  the  proc	 is  a	dynamically  allocated
	      string  that  will  be released by the Tcl library via a call to
	      ckfree.  Must not be specified at the same time as TCL_TRACE_RE‐
	      SULT_OBJECT.

       TCL_TRACE_RESULT_OBJECT
	      The  result of invoking the proc is a Tcl_Obj* (cast to a char*)
	      with a reference count of at least one.  The ownership  of  that
	      reference	 will be transferred to the Tcl core for release (when
	      the core has finished with it) via a call	 to  Tcl_DecrRefCount.
	      Must  not	 be specified at the same time as TCL_TRACE_RESULT_DY‐
	      NAMIC.

       Whenever one of the specified operations occurs on the  variable,  proc
       will  be	 invoked.   It should have arguments and result that match the
       type Tcl_VarTraceProc:

	      typedef char *Tcl_VarTraceProc(
		      ClientData clientData,
		      Tcl_Interp *interp,
		      const char *name1,
		      const char *name2,
		      int flags);

       The clientData and interp parameters will have the same values as those
       passed  to  Tcl_TraceVar	 when the trace was created.  ClientData typi‐
       cally points to an application-specific data structure  that  describes
       what  to do when proc is invoked.  Name1 and name2 give the name of the
       traced variable in the normal two-part form  (see  the  description  of
       Tcl_TraceVar2  below  for  details).   Flags is an OR-ed combination of
       bits  providing	several	 pieces	 of  information.   One	 of  the  bits
       TCL_TRACE_READS, TCL_TRACE_WRITES, TCL_TRACE_ARRAY, or TCL_TRACE_UNSETS
       will be set in flags to indicate which operation is being performed  on
       the  variable.	The bit TCL_GLOBAL_ONLY will be set whenever the vari‐
       able being accessed is a global one not	accessible  from  the  current
       level  of  procedure  call:  the trace procedure will need to pass this
       flag back to variable-related procedures like Tcl_GetVar if it attempts
       to  access  the variable.  The bit TCL_NAMESPACE_ONLY will be set when‐
       ever the variable being accessed is a namespace one not accessible from
       the  current level of procedure call:  the trace procedure will need to
       pass this flag back to variable-related procedures like	Tcl_GetVar  if
       it  attempts  to access the variable.  The bit TCL_TRACE_DESTROYED will
       be set in flags if the trace is about to be destroyed;	this  informa‐
       tion  may  be  useful  to proc so that it can clean up its own internal
       data structures (see the section TCL_TRACE_DESTROYED below for more de‐
       tails).	Lastly, the bit TCL_INTERP_DESTROYED will be set if the entire
       interpreter is being destroyed.	When this bit is set, proc must be es‐
       pecially	 careful in the things it does (see the section TCL_INTERP_DE‐
       STROYED below).	The trace procedure's return value should normally  be
       NULL;  see ERROR RETURNS below for information on other possibilities.

       Tcl_UntraceVar  may  be used to remove a trace.	If the variable speci‐
       fied by interp, varName, and flags has a trace set  with	 flags,	 proc,
       and  clientData,	 then  the corresponding trace is removed.  If no such
       trace exists, then the call to Tcl_UntraceVar has no effect.  The  same
       bits are valid for flags as for calls to Tcl_TraceVar.

       Tcl_VarTraceInfo	 may  be used to retrieve information about traces set
       on a given variable.  The return value  from  Tcl_VarTraceInfo  is  the
       clientData  associated  with  a particular trace.  The trace must be on
       the variable specified by the  interp,  varName,	 and  flags  arguments
       (only  the  TCL_GLOBAL_ONLY  and	 TCL_NAMESPACE_ONLY bits from flags is
       used;  other bits are ignored) and its trace procedure must the same as
       the proc argument.  If the prevClientData argument is NULL then the re‐
       turn value corresponds to the first (most  recently  created)  matching
       trace,  or NULL if there are no matching traces.	 If the prevClientData
       argument is not NULL, then it should be the return value from a	previ‐
       ous  call to Tcl_VarTraceInfo.  In this case, the new return value will
       correspond to the next matching trace after the	one  whose  clientData
       matches	prevClientData,	 or NULL if no trace matches prevClientData or
       if there are no more matching traces after it.  This mechanism makes it
       possible	 to  step  through all of the traces for a given variable that
       have the same proc.

TWO-PART NAMES
       The procedures Tcl_TraceVar2,  Tcl_UntraceVar2,	and  Tcl_VarTraceInfo2
       are  identical  to  Tcl_TraceVar, Tcl_UntraceVar, and Tcl_VarTraceInfo,
       respectively, except that the name of  the  variable  consists  of  two
       parts.	Name1  gives the name of a scalar variable or array, and name2
       gives the name of an element within an  array.	When  name2  is	 NULL,
       name1  may  contain both an array and an element name: if the name con‐
       tains an open parenthesis and ends with a close parenthesis,  then  the
       value  between the parentheses is treated as an element name (which can
       have any string value) and the characters before the first open	paren‐
       thesis  are treated as the name of an array variable.  If name2 is NULL
       and name1 does not refer to an array element it means that  either  the
       variable	 is  a	scalar	or  the trace is to be set on the entire array
       rather than an individual element (see  WHOLE-ARRAY  TRACES  below  for
       more information).

ACCESSING VARIABLES DURING TRACES
       During  read,  write,  and  array traces, the trace procedure can read,
       write, or unset the traced variable using Tcl_GetVar2, Tcl_SetVar2, and
       other procedures.  While proc is executing, traces are temporarily dis‐
       abled for the variable, so that calls to	 Tcl_GetVar2  and  Tcl_SetVar2
       will  not  cause	 proc  or  other trace procedures to be invoked again.
       Disabling only occurs for the variable whose trace procedure is active;
       accesses	 to other variables will still be traced.  However, if a vari‐
       able is unset during a read or write trace then unset  traces  will  be
       invoked.

       During  unset traces the variable has already been completely expunged.
       It is possible for the trace procedure to read or write	the  variable,
       but  this  will	be a new version of the variable.  Traces are not dis‐
       abled during unset traces as they are for read and  write  traces,  but
       existing	 traces	 have  been removed from the variable before any trace
       procedures are invoked.	If new traces are set by  unset	 trace	proce‐
       dures,  these traces will be invoked on accesses to the variable by the
       trace procedures.

CALLBACK TIMING
       When read tracing has been specified for a variable, the	 trace	proce‐
       dure  will  be invoked whenever the variable's value is read.  This in‐
       cludes set Tcl commands, $-notation in Tcl commands, and invocations of
       the Tcl_GetVar and Tcl_GetVar2 procedures.  Proc is invoked just before
       the variable's value is returned.  It may modify the value of the vari‐
       able to affect what is returned by the traced access.  If it unsets the
       variable then the access will return an error just as if	 the  variable
       never existed.

       When  write tracing has been specified for a variable, the trace proce‐
       dure will be invoked whenever the variable's value is  modified.	  This
       includes	 set  commands, commands that modify variables as side effects
       (such as catch and scan), and calls to the Tcl_SetVar  and  Tcl_SetVar2
       procedures).   Proc will be invoked after the variable's value has been
       modified, but before the new value of the variable has  been  returned.
       It  may	modify the value of the variable to override the change and to
       determine the value actually returned by	 the  traced  access.	If  it
       deletes	the  variable  then  the  traced  access  will return an empty
       string.

       When array tracing has been specified, the trace procedure will be  in‐
       voked  at the beginning of the array command implementation, before any
       of the operations like get, set, or names have been invoked.  The trace
       procedure  can  modify  the array elements with Tcl_SetVar and Tcl_Set‐
       Var2.

       When unset tracing has been specified, the trace procedure will be  in‐
       voked  whenever	the  variable is destroyed.  The traces will be called
       after the variable has been completely unset.

WHOLE-ARRAY TRACES
       If a call to Tcl_TraceVar or Tcl_TraceVar2 specifies the name of an ar‐
       ray  variable  without  an index into the array, then the trace will be
       set on the array as a whole.  This means	 that  proc  will  be  invoked
       whenever	 any element of the array is accessed in the ways specified by
       flags.  When an array is unset, a whole-array  trace  will  be  invoked
       just  once,  with  name1 equal to the name of the array and name2 NULL;
       it will not be invoked once for each element.

MULTIPLE TRACES
       It is possible for multiple traces to exist on the same variable.  When
       this  happens,  all of the trace procedures will be invoked on each ac‐
       cess, in order from  most-recently-created  to  least-recently-created.
       When  there  exist whole-array traces for an array as well as traces on
       individual elements, the whole-array traces are invoked before the  in‐
       dividual-element	 traces.  If a read or write trace unsets the variable
       then all of the unset traces will be invoked but the remainder  of  the
       read and write traces will be skipped.

ERROR RETURNS
       Under normal conditions trace procedures should return NULL, indicating
       successful completion.  If proc returns a non-NULL value	 it  signifies
       that an error occurred.	The return value must be a pointer to a static
       character string containing an error message, unless (exactly  one  of)
       the  TCL_TRACE_RESULT_DYNAMIC and TCL_TRACE_RESULT_OBJECT flags is set,
       which specify that the result is either a dynamic  string  (to  be  re‐
       leased  with  ckfree)  or  a Tcl_Obj* (cast to char* and to be released
       with Tcl_DecrRefCount) containing the error message.  If a trace proce‐
       dure returns an error, no further traces are invoked for the access and
       the traced access aborts with the given message.	 Trace procedures  can
       use  this  facility  to make variables read-only, for example (but note
       that the value of the variable will already have been  modified	before
       the  trace procedure is called, so the trace procedure will have to re‐
       store the correct value).

       The return value from proc is only used during read and write  tracing.
       During unset traces, the return value is ignored and all relevant trace
       procedures will always be invoked.

RESTRICTIONS
       A trace procedure can be called at any time, even when there  are  par‐
       tially  formed  results stored in the interpreter.  If the trace proce‐
       dure does anything that could  damage  this  result  (such  as  calling
       Tcl_Eval) then it must use the Tcl_SaveInterpState and related routines
       to save and restore the original state of the interpreter before it re‐
       turns.

UNDEFINED VARIABLES
       It is legal to set a trace on an undefined variable.  The variable will
       still appear to be undefined until the first time its value is set.  If
       an  undefined  variable	is  traced and then unset, the unset will fail
       with an error (“no such variable”), but the trace procedure will	 still
       be invoked.

TCL_TRACE_DESTROYED FLAG
       In  an  unset  callback	to proc, the TCL_TRACE_DESTROYED bit is set in
       flags if the trace is being removed as part of the deletion.  Traces on
       a  variable  are	 always removed whenever the variable is deleted;  the
       only time TCL_TRACE_DESTROYED is not set is for a whole-array trace in‐
       voked when only a single element of an array is unset.

TCL_INTERP_DESTROYED
       When  an	 interpreter  is destroyed, unset traces are called for all of
       its variables.  The TCL_INTERP_DESTROYED bit will be set in  the	 flags
       argument	 passed to the trace procedures.  Trace procedures must be ex‐
       tremely careful in what they do if the TCL_INTERP_DESTROYED bit is set.
       It  is  not safe for the procedures to invoke any Tcl procedures on the
       interpreter, since its state is partially deleted.  All that trace pro‐
       cedures	should	do  under  these circumstances is to clean up and free
       their own internal data structures.

BUGS
       Tcl does not do any error checking to  prevent  trace  procedures  from
       misusing the interpreter during traces with TCL_INTERP_DESTROYED set.

       Array  traces  are not yet integrated with the Tcl info exists command,
       nor is there Tcl-level access to array traces.

SEE ALSO
       trace(n)

KEYWORDS
       clientData, trace, variable



Tcl				      7.4		       Tcl_TraceVar(3)

Notifier(3)		    Tcl Library Procedures		   Notifier(3)



______________________________________________________________________________

NAME
       Tcl_CreateEventSource,	 Tcl_DeleteEventSource,	  Tcl_SetMaxBlockTime,
       Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert,  Tcl_GetCurrent‐
       Thread,	 Tcl_DeleteEvents,   Tcl_InitNotifier,	 Tcl_FinalizeNotifier,
       Tcl_WaitForEvent,  Tcl_AlertNotifier,   Tcl_SetTimer,   Tcl_ServiceAll,
       Tcl_ServiceEvent,  Tcl_GetServiceMode, Tcl_SetServiceMode, Tcl_Service‐
       ModeHook, Tcl_SetNotifier - the event queue and notifier interfaces

SYNOPSIS
       #include <tcl.h>

       void
       Tcl_CreateEventSource(setupProc, checkProc, clientData)

       void
       Tcl_DeleteEventSource(setupProc, checkProc, clientData)

       void
       Tcl_SetMaxBlockTime(timePtr)

       void
       Tcl_QueueEvent(evPtr, position)

       void
       Tcl_ThreadQueueEvent(threadId, evPtr, position)

       void
       Tcl_ThreadAlert(threadId)

       Tcl_ThreadId
       Tcl_GetCurrentThread()

       void
       Tcl_DeleteEvents(deleteProc, clientData)

       ClientData
       Tcl_InitNotifier()

       void
       Tcl_FinalizeNotifier(clientData)

       int
       Tcl_WaitForEvent(timePtr)

       void
       Tcl_AlertNotifier(clientData)

       void
       Tcl_SetTimer(timePtr)

       int
       Tcl_ServiceAll()

       int
       Tcl_ServiceEvent(flags)

       int
       Tcl_GetServiceMode()

       int
       Tcl_SetServiceMode(mode)

       void
       Tcl_ServiceModeHook(mode)

       void
       Tcl_SetNotifier(notifierProcPtr)

ARGUMENTS
       Tcl_EventSetupProc *setupProc (in)		  Procedure to	invoke
							  to prepare for event
							  wait		    in
							  Tcl_DoOneEvent.

       Tcl_EventCheckProc *checkProc (in)		  Procedure	   for
							  Tcl_DoOneEvent    to
							  invoke after waiting
							  for events.	Checks
							  to see if any events
							  have	occurred  and,
							  if so, queues them.

       ClientData clientData (in)			  Arbitrary   one-word
							  value to pass to se‐
							  tupProc,  checkProc,
							  or deleteProc.

       const Tcl_Time *timePtr (in)			  Indicates the	 maxi‐
							  mum  amount  of time
							  to   wait   for   an
							  event.     This   is
							  specified as an  in‐
							  terval  (how long to
							  wait), not an	 abso‐
							  lute	time  (when to
							  wakeup).    If   the
							  pointer   passed  to
							  Tcl_WaitForEvent  is
							  NULL, it means there
							  is no	 maximum  wait
							  time:	  wait forever
							  if necessary.

       Tcl_Event *evPtr (in)				  An event to  add  to
							  the	event	queue.
							  The storage for  the
							  event must have been
							  allocated   by   the
							  caller using Tcl_Al‐
							  loc or ckalloc.

       Tcl_QueuePosition position (in)			  Where to add the new
							  event	 in the queue:
							  TCL_QUEUE_TAIL,
							  TCL_QUEUE_HEAD,   or
							  TCL_QUEUE_MARK.

       Tcl_ThreadId threadId (in)			  A unique  identifier
							  for a thread.

       Tcl_EventDeleteProc *deleteProc (in)		  Procedure  to invoke
							  for	each	queued
							  event	 in  Tcl_Dele‐
							  teEvents.

       int flags (in)					  What types of events
							  to  service.	 These
							  flags are  the  same
							  as  those  passed to
							  Tcl_DoOneEvent.

       int mode (in)					  Indicates    whether
							  events   should   be
							  serviced by Tcl_Ser‐
							  viceAll.    Must  be
							  one	of    TCL_SER‐
							  VICE_NONE	    or
							  TCL_SERVICE_ALL.

       Tcl_NotifierProcs* notifierProcPtr (in)		  Structure  of	 func‐
							  tion	 pointers  de‐
							  scribing    notifier
							  procedures  that are
							  to replace the  ones
							  installed in the ex‐
							  ecutable.   See  RE‐
							  PLACING THE NOTIFIER
							  for details.
______________________________________________________________________________

INTRODUCTION
       The interfaces described here are used to customize the Tcl event loop.
       The two most common customizations are to add new sources of events and
       to merge Tcl's event loop with some other event loop, such as one  pro‐
       vided  by an application in which Tcl is embedded.  Each of these tasks
       is described in a separate section below.

       The procedures in this manual entry are	the  building  blocks  out  of
       which the Tcl event notifier is constructed.  The event notifier is the
       lowest layer in the Tcl event mechanism.	 It consists of three things:

       [1]    Event sources: these represent the ways in which events  can  be
	      generated.   For example, there is a timer event source that im‐
	      plements the Tcl_CreateTimerHandler procedure and the after com‐
	      mand,  and  there	 is  a	file  event source that implements the
	      Tcl_CreateFileHandler  procedure	on  Unix  systems.   An	 event
	      source must work with the notifier to detect events at the right
	      times, record them on the event  queue,  and  eventually	notify
	      higher-level  software  that they have occurred.	The procedures
	      Tcl_CreateEventSource,   Tcl_DeleteEventSource,	and   Tcl_Set‐
	      MaxBlockTime, Tcl_QueueEvent, and Tcl_DeleteEvents are used pri‐
	      marily by event sources.

       [2]    The event queue: for non-threaded applications, there is a  sin‐
	      gle queue for the whole application, containing events that have
	      been detected but not yet serviced.  Event sources place	events
	      onto  the queue so that they may be processed in order at appro‐
	      priate times during the event loop. The event queue guarantees a
	      fair  discipline	of event handling, so that no event source can
	      starve the others.  It also allows events to be saved  for  ser‐
	      vicing  at a future time.	 Threaded applications work in a simi‐
	      lar manner, except that there is a separate event queue for each
	      thread  containing  a  Tcl  interpreter.	Tcl_QueueEvent is used
	      (primarily by event sources) to add events to  the  event	 queue
	      and  Tcl_DeleteEvents  is	 used  to remove events from the queue
	      without	processing   them.    In   a   threaded	  application,
	      Tcl_QueueEvent  adds an event to the current thread's queue, and
	      Tcl_ThreadQueueEvent adds an event to  a	queue  in  a  specific
	      thread.

       [3]    The  event  loop: in order to detect and process events, the ap‐
	      plication enters a loop that waits for events to	occur,	places
	      them on the event queue, and then processes them.	 Most applica‐
	      tions will do this  by  calling  the  procedure  Tcl_DoOneEvent,
	      which is described in a separate manual entry.

       Most  Tcl applications need not worry about any of the internals of the
       Tcl notifier.  However, the notifier now has enough flexibility	to  be
       retargeted  either  for a new platform or to use an external event loop
       (such as the Motif event loop, when Tcl is embedded in a Motif applica‐
       tion).	The  procedures Tcl_WaitForEvent and Tcl_SetTimer are normally
       implemented by Tcl, but may be replaced with new versions  to  retarget
       the  notifier (the Tcl_InitNotifier, Tcl_AlertNotifier, Tcl_FinalizeNo‐
       tifier,	Tcl_Sleep,  Tcl_CreateFileHandler,  and	 Tcl_DeleteFileHandler
       must  also be replaced; see CREATING A NEW NOTIFIER below for details).
       The procedures  Tcl_ServiceAll,	Tcl_ServiceEvent,  Tcl_GetServiceMode,
       and Tcl_SetServiceMode are provided to help connect Tcl's event loop to
       an external event loop such as Motif's.

NOTIFIER BASICS
       The easiest way to understand how the notifier  works  is  to  consider
       what happens when Tcl_DoOneEvent is called.  Tcl_DoOneEvent is passed a
       flags argument that indicates what sort of events it is OK  to  process
       and   also   whether   or   not	to  block  if  no  events  are	ready.
       Tcl_DoOneEvent does the following things:

       [1]    Check the event queue to see if it contains any events that  can
	      be serviced.  If so, service the first possible event, remove it
	      from the queue, and return.  It does this	 by  calling  Tcl_Ser‐
	      viceEvent and passing in the flags argument.

       [2]    Prepare  to  block for an event.	To do this, Tcl_DoOneEvent in‐
	      vokes a setup procedure in each event source.  The event	source
	      will  perform  event-source specific initialization and possibly
	      call Tcl_SetMaxBlockTime to limit how long Tcl_WaitForEvent will
	      block if no new events occur.

       [3]    Call  Tcl_WaitForEvent.	This  procedure is implemented differ‐
	      ently on different platforms;  it waits for an event  to	occur,
	      based  on the information provided by the event sources.	It may
	      cause the application to block if timePtr specifies an  interval
	      other  than 0.  Tcl_WaitForEvent returns when something has hap‐
	      pened, such as a file becoming readable or the interval given by
	      timePtr  expiring.   If there are no events for Tcl_WaitForEvent
	      to wait for, so that it would block forever, then it returns im‐
	      mediately and Tcl_DoOneEvent returns 0.

       [4]    Call  a  check procedure in each event source.  The check proce‐
	      dure determines whether any events of interest  to  this	source
	      occurred.	 If so, the events are added to the event queue.

       [5]    Check  the event queue to see if it contains any events that can
	      be serviced.  If so, service the first possible event, remove it
	      from the queue, and return.

       [6]    See  if  there  are idle callbacks pending. If so, invoke all of
	      them and return.

       [7]    Either return 0 to indicate that no events  were	ready,	or  go
	      back to step [2] if blocking was requested by the caller.

CREATING A NEW EVENT SOURCE
       An  event  source consists of three procedures invoked by the notifier,
       plus additional C procedures that are invoked by higher-level  code  to
       arrange for event-driven callbacks.  The three procedures called by the
       notifier consist of the setup and  check	 procedures  described	above,
       plus  an	 additional procedure that is invoked when an event is removed
       from the event queue for servicing.

       The procedure Tcl_CreateEventSource creates a new  event	 source.   Its
       arguments specify the setup procedure and check procedure for the event
       source.	SetupProc should match the following prototype:

	      typedef void Tcl_EventSetupProc(
		      ClientData clientData,
		      int flags);

       The clientData argument will be the same as the clientData argument  to
       Tcl_CreateEventSource;  it is typically used to point to private infor‐
       mation managed by the event source.  The flags  argument	 will  be  the
       same as the flags argument passed to Tcl_DoOneEvent except that it will
       never be 0 (Tcl_DoOneEvent replaces 0 with TCL_ALL_EVENTS).  Flags  in‐
       dicates	what  kinds  of events should be considered; if the bit corre‐
       sponding to this event source is not set, the event source  should  re‐
       turn  immediately  without doing anything.  For example, the file event
       source checks for the TCL_FILE_EVENTS bit.

       SetupProc's job is to make sure that  the  application  wakes  up  when
       events  of  the	desired type occur.  This is typically done in a plat‐
       form-dependent fashion.	For example, under Unix an event source	 might
       call Tcl_CreateFileHandler; under Windows it might request notification
       with a Windows event.  For timer-driven event  sources  such  as	 timer
       events  or any polled event, the event source can call Tcl_SetMaxBlock‐
       Time to force the application to wake up after a specified time even if
       no  events have occurred.  If no event source calls Tcl_SetMaxBlockTime
       then Tcl_WaitForEvent will wait as long as necessary for	 an  event  to
       occur;  otherwise,  it  will only wait as long as the shortest interval
       passed to Tcl_SetMaxBlockTime by one of the event sources.  If an event
       source knows that it already has events ready to report, it can request
       a zero maximum block time.  For example, the setup procedure for the  X
       event source looks to see if there are events already queued.  If there
       are, it calls Tcl_SetMaxBlockTime with a 0 block time so that Tcl_Wait‐
       ForEvent	 does  not  block if there is no new data on the X connection.
       The timePtr argument to Tcl_WaitForEvent points to a structure that de‐
       scribes a time interval in seconds and microseconds:

	      typedef struct Tcl_Time {
		  long sec;
		  long usec;
	      } Tcl_Time;

       The usec field should be less than 1000000.

       Information  provided  to Tcl_SetMaxBlockTime is only used for the next
       call to Tcl_WaitForEvent; it is discarded  after	 Tcl_WaitForEvent  re‐
       turns.	The next time an event wait is done each of the event sources'
       setup procedures will be called again, and they can specify new	infor‐
       mation for that event wait.

       If   the	  application	uses   an  external  event  loop  rather  than
       Tcl_DoOneEvent, the event sources may need to call  Tcl_SetMaxBlockTime
       at other times.	For example, if a new event handler is registered that
       needs to poll for events, the event source may call Tcl_SetMaxBlockTime
       to  set the block time to zero to force the external event loop to call
       Tcl.  In this case, Tcl_SetMaxBlockTime invokes Tcl_SetTimer  with  the
       shortest	 interval  seen	 since	the  last  call	 to  Tcl_DoOneEvent or
       Tcl_ServiceAll.

       In addition to the generic procedure Tcl_SetMaxBlockTime,  other	 plat‐
       form-specific  procedures may also be available for setupProc, if there
       is additional information needed by Tcl_WaitForEvent on that  platform.
       For example, on Unix systems the Tcl_CreateFileHandler interface can be
       used to wait for file events.

       The second procedure provided by each event source is its check	proce‐
       dure,  indicated	 by  the  checkProc argument to Tcl_CreateEventSource.
       CheckProc must match the following prototype:

	      typedef void Tcl_EventCheckProc(
		      ClientData clientData,
		      int flags);

       The arguments to this procedure are the same as	those  for  setupProc.
       CheckProc  is invoked by Tcl_DoOneEvent after it has waited for events.
       Presumably at least one event source is now prepared to queue an event.
       Tcl_DoOneEvent  calls  each  of	the event sources in turn, so they all
       have a chance to queue any events that are ready.  The check  procedure
       does  two  things.   First,  it	must see if any events have triggered.
       Different event sources do this in different ways.

       If an event source's check procedure detects an interesting  event,  it
       must  add the event to Tcl's event queue.  To do this, the event source
       calls Tcl_QueueEvent.  The evPtr argument is a pointer to a dynamically
       allocated  structure  containing the event (see below for more informa‐
       tion on memory management issues).  Each event source  can  define  its
       own event structure with whatever information is relevant to that event
       source.	However, the first element of the structure must be  a	struc‐
       ture  of type Tcl_Event, and the address of this structure is used when
       communicating between the event source and the rest of the notifier.  A
       Tcl_Event has the following definition:

	      typedef struct {
		  Tcl_EventProc *proc;
		  struct Tcl_Event *nextPtr;
	      } Tcl_Event;

       The  event source must fill in the proc field of the event before call‐
       ing Tcl_QueueEvent.  The nextPtr is used to link together the events in
       the queue and should not be modified by the event source.

       An event may be added to the queue at any of three positions, depending
       on the position argument to Tcl_QueueEvent:

       TCL_QUEUE_TAIL	       Add the event at the back of the queue, so that
			       all  other  pending  events  will  be  serviced
			       first.  This is almost always the  right	 place
			       for new events.

       TCL_QUEUE_HEAD	       Add  the	 event	at  the front of the queue, so
			       that it	will  be  serviced  before  all	 other
			       queued events.

       TCL_QUEUE_MARK	       Add the event at the front of the queue, unless
			       there are other events at the front whose posi‐
			       tion  is	 TCL_QUEUE_MARK;   if  so, add the new
			       event  just  after  all	other	TCL_QUEUE_MARK
			       events.	 This value of position is used to in‐
			       sert an ordered sequence of events at the front
			       of  the	queue,	such  as a series of Enter and
			       Leave events synthesized during a grab  or  un‐
			       grab operation in Tk.

       When it is time to handle an event from the queue (steps 1 and 4 above)
       Tcl_ServiceEvent will invoke the proc specified	in  the	 first	queued
       Tcl_Event structure.  Proc must match the following prototype:

	      typedef int Tcl_EventProc(
		      Tcl_Event *evPtr,
		      int flags);

       The first argument to proc is a pointer to the event, which will be the
       same as the first argument to the Tcl_QueueEvent call  that  added  the
       event  to the queue.  The second argument to proc is the flags argument
       for the current call to Tcl_ServiceEvent;  this is used	by  the	 event
       source to return immediately if its events are not relevant.

       It is up to proc to handle the event, typically by invoking one or more
       Tcl commands or C-level callbacks.  Once the event source has  finished
       handling	 the  event it returns 1 to indicate that the event can be re‐
       moved from the queue.  If for some reason the event source decides that
       the  event  cannot be handled at this time, it may return 0 to indicate
       that the event should be deferred for processing later;	in  this  case
       Tcl_ServiceEvent	 will go on to the next event in the queue and attempt
       to service it.  There are several reasons why an event source might de‐
       fer an event.  One possibility is that events of this type are excluded
       by the flags argument.  For example, the file event source will	always
       return 0 if the TCL_FILE_EVENTS bit is not set in flags.	 Another exam‐
       ple of deferring events happens in Tk if Tk_RestrictEvents has been in‐
       voked to defer certain kinds of window events.

       When  proc  returns  1, Tcl_ServiceEvent will remove the event from the
       event queue and free its storage.  Note that the storage for  an	 event
       must be allocated by the event source (using Tcl_Alloc or the Tcl macro
       ckalloc) before	calling	 Tcl_QueueEvent,  but  it  will	 be  freed  by
       Tcl_ServiceEvent, not by the event source.

       Threaded	 applications work in a similar manner, except that there is a
       separate event queue for each  thread  containing  a  Tcl  interpreter.
       Calling	Tcl_QueueEvent in a multithreaded application adds an event to
       the current thread's queue.  To add an event to another thread's queue,
       use  Tcl_ThreadQueueEvent.  Tcl_ThreadQueueEvent accepts as an argument
       a Tcl_ThreadId argument, which uniquely identifies a thread  in	a  Tcl
       application.   To  obtain  the Tcl_ThreadId for the current thread, use
       the Tcl_GetCurrentThread procedure.  (A thread would then need to  pass
       this  identifier	 to  other threads for those threads to be able to add
       events to its queue.)  After adding an event to another thread's queue,
       you  then  typically  need  to  call  Tcl_ThreadAlert to “wake up” that
       thread's notifier to alert it to the new event.

       Tcl_DeleteEvents can be used to explicitly remove one  or  more	events
       from  the  event	 queue.	 Tcl_DeleteEvents calls proc for each event in
       the queue, deleting those for with the procedure returns 1.  Events for
       which the procedure returns 0 are left in the queue.  Proc should match
       the following prototype:

	      typedef int Tcl_EventDeleteProc(
		      Tcl_Event *evPtr,
		      ClientData clientData);

       The clientData argument will be the same as the clientData argument  to
       Tcl_DeleteEvents;  it is typically used to point to private information
       managed by the event source.  The evPtr will point to the next event in
       the queue.

       Tcl_DeleteEventSource  deletes  an event source.	 The setupProc, check‐
       Proc, and clientData arguments must exactly match those provided to the
       Tcl_CreateEventSource  for  the event source to be deleted.  If no such
       source exists, Tcl_DeleteEventSource has no effect.

CREATING A NEW NOTIFIER
       The notifier consists of all the procedures described  in  this	manual
       entry,  plus  Tcl_DoOneEvent  and Tcl_Sleep, which are available on all
       platforms, and Tcl_CreateFileHandler and	 Tcl_DeleteFileHandler,	 which
       are  Unix-specific.  Most of these procedures are generic, in that they
       are the same for all notifiers.	However, none of  the  procedures  are
       notifier-dependent:   Tcl_InitNotifier,	Tcl_AlertNotifier,  Tcl_Final‐
       izeNotifier, Tcl_SetTimer, Tcl_Sleep, Tcl_WaitForEvent, Tcl_CreateFile‐
       Handler,	 Tcl_DeleteFileHandler	and Tcl_ServiceModeHook.  To support a
       new platform or to integrate Tcl	 with  an  application-specific	 event
       loop, you must write new versions of these procedures.

       Tcl_InitNotifier initializes the notifier state and returns a handle to
       the notifier state.  Tcl calls this procedure when initializing	a  Tcl
       interpreter.   Similarly, Tcl_FinalizeNotifier shuts down the notifier,
       and is called by Tcl_Finalize when shutting down a Tcl interpreter.

       Tcl_WaitForEvent is the lowest-level procedure in the notifier;	it  is
       responsible  for	 waiting  for an “interesting” event to occur or for a
       given time to elapse.  Before Tcl_WaitForEvent is invoked, each of  the
       event sources' setup procedure will have been invoked.  The timePtr ar‐
       gument to Tcl_WaitForEvent gives the  maximum  time  to	block  for  an
       event,  based  on calls to Tcl_SetMaxBlockTime made by setup procedures
       and on other information (such as the TCL_DONT_WAIT bit in flags).

       Ideally, Tcl_WaitForEvent should only wait for an event	to  occur;  it
       should  not actually process the event in any way.  Later on, the event
       sources will process the raw events and create Tcl_Events on the	 event
       queue  in their checkProc procedures.  However, on some platforms (such
       as Windows) this is not possible; events may be processed in  Tcl_Wait‐
       ForEvent, including queuing Tcl_Events and more (for example, callbacks
       for native widgets may be invoked).  The return	value  from  Tcl_Wait‐
       ForEvent	 must  be  either  0,  1, or -1.  On platforms such as Windows
       where events get processed in Tcl_WaitForEvent, a  return  value	 of  1
       means  that  there  may be more events still pending that have not been
       processed.  This is a sign to the caller that it	 must  call  Tcl_Wait‐
       ForEvent	 again if it wants all pending events to be processed. A 0 re‐
       turn value means that calling Tcl_WaitForEvent again will not have  any
       effect:	either	this  is  a platform where Tcl_WaitForEvent only waits
       without doing any event processing, or Tcl_WaitForEvent knows for  sure
       that  there  are	 no additional events to process (e.g. it returned be‐
       cause the time elapsed).	 Finally, a return value of -1 means that  the
       event loop is no longer operational and the application should probably
       unwind and terminate.  Under Windows this happens when a	 WM_QUIT  mes‐
       sage  is	 received;  under  Unix it happens when Tcl_WaitForEvent would
       have waited forever because there were no active event sources and  the
       timeout was infinite.

       Tcl_AlertNotifier  is  used  in multithreaded applications to allow any
       thread to “wake up” the notifier to alert  it  to  new  events  on  its
       queue.	Tcl_AlertNotifier  requires as an argument the notifier handle
       returned by Tcl_InitNotifier.

       If the notifier will be used with an external event loop, then it  must
       also  support  the  Tcl_SetTimer interface.  Tcl_SetTimer is invoked by
       Tcl_SetMaxBlockTime whenever the maximum blocking  time	has  been  re‐
       duced.	Tcl_SetTimer should arrange for the external event loop to in‐
       voke Tcl_ServiceAll after the specified interval even if no events have
       occurred.  This interface is needed because Tcl_WaitForEvent is not in‐
       voked when there is an external event loop.  If the notifier will  only
       be used from Tcl_DoOneEvent, then Tcl_SetTimer need not do anything.

       Tcl_ServiceModeHook  is	called	by the platform-independent portion of
       the notifier when client code makes a call to Tcl_SetServiceMode.  This
       hook  is	 provided  to  support	operating systems that require special
       event handling when the application is in a modal loop (the Windows no‐
       tifier, for instance, uses this hook to create a communication window).

       On  Unix systems, the file event source also needs support from the no‐
       tifier.	The file event source consists	of  the	 Tcl_CreateFileHandler
       and  Tcl_DeleteFileHandler  procedures,	which  are  described  in  the
       Tcl_CreateFileHandler manual page.

       The Tcl_Sleep and Tcl_DoOneEvent interfaces are described in their  re‐
       spective manual pages.

       The  easiest way to create a new notifier is to look at the code for an
       existing notifier, such as the files unix/tclUnixNotfy.c or win/tclWin‐
       Notify.c in the Tcl source distribution.

REPLACING THE NOTIFIER
       A notifier that has been written according to the conventions above can
       also be installed in a running process in place of the  standard	 noti‐
       fier.   This  mechanism is used so that a single executable can be used
       (with the standard notifier) as a stand-alone program and reused	 (with
       a  replacement notifier in a loadable extension) as an extension to an‐
       other program, such as a Web browser plugin.

       To do this, the extension makes a call  to  Tcl_SetNotifier  passing  a
       pointer	to  a Tcl_NotifierProcs data structure.	 The structure has the
       following layout:

	      typedef struct Tcl_NotifierProcs {
		  Tcl_SetTimerProc *setTimerProc;
		  Tcl_WaitForEventProc *waitForEventProc;
		  Tcl_CreateFileHandlerProc *createFileHandlerProc;
		  Tcl_DeleteFileHandlerProc *deleteFileHandlerProc;
		  Tcl_InitNotifierProc *initNotifierProc;
		  Tcl_FinalizeNotifierProc *finalizeNotifierProc;
		  Tcl_AlertNotifierProc *alertNotifierProc;
		  Tcl_ServiceModeHookProc *serviceModeHookProc;
	      } Tcl_NotifierProcs;

       Following the call  to  Tcl_SetNotifier,	 the  pointers	given  in  the
       Tcl_NotifierProcs  structure  replace  whatever	notifier  had been in‐
       stalled in the process.

       It is extraordinarily unwise to replace a running  notifier.  Normally,
       Tcl_SetNotifier	should be called at process initialization time before
       the first call to Tcl_InitNotifier.

EXTERNAL EVENT LOOPS
       The notifier interfaces are designed so that Tcl can be	embedded  into
       applications  that  have	 their own private event loops.	 In this case,
       the application does not call Tcl_DoOneEvent except in the case of  re‐
       cursive	event loops such as calls to the Tcl commands update or vwait.
       Most of the time is spent in the external event loop  of	 the  applica‐
       tion.   In  this	 case the notifier must arrange for the external event
       loop to call back into Tcl when something happens on  the  various  Tcl
       event  sources.	 These	callbacks  should  arrange for appropriate Tcl
       events to be placed on the Tcl event queue.

       Because the external event loop is not calling Tcl_DoOneEvent on a reg‐
       ular basis, it is up to the notifier to arrange for Tcl_ServiceEvent to
       be called whenever events are pending on the Tcl event queue.  The eas‐
       iest  way  to  do  this	is to invoke Tcl_ServiceAll at the end of each
       callback from the external event loop.  This will ensure	 that  all  of
       the  event  sources are polled, any queued events are serviced, and any
       pending idle handlers are processed before returning control to the ap‐
       plication.  In addition, event sources that need to poll for events can
       call Tcl_SetMaxBlockTime to force the external event loop to  call  Tcl
       even if no events are available on the system event queue.

       As  a  side  effect  of processing events detected in the main external
       event loop, Tcl may invoke Tcl_DoOneEvent to start  a  recursive	 event
       loop  in	 commands like vwait.  Tcl_DoOneEvent will invoke the external
       event loop, which will result in callbacks as described in the  preced‐
       ing  paragraph, which will result in calls to Tcl_ServiceAll.  However,
       in these cases it is undesirable to service events  in  Tcl_ServiceAll.
       Servicing  events there is unnecessary because control will immediately
       return to the external event loop and hence  to	Tcl_DoOneEvent,	 which
       can service the events itself.  Furthermore, Tcl_DoOneEvent is supposed
       to service only a single event, whereas	Tcl_ServiceAll	normally  ser‐
       vices  all  pending  events.   To handle this situation, Tcl_DoOneEvent
       sets a flag for Tcl_ServiceAll that causes it to return without servic‐
       ing  any	 events.  This flag is called the service mode; Tcl_DoOneEvent
       restores it to its previous value before it returns.

       In some cases, however, it may be necessary for Tcl_ServiceAll to  ser‐
       vice  events  even  when it has been invoked from Tcl_DoOneEvent.  This
       happens when there is yet another recursive event loop invoked  via  an
       event  handler  called by Tcl_DoOneEvent (such as one that is part of a
       native widget).	In this case, Tcl_DoOneEvent may not have a chance  to
       service	events so Tcl_ServiceAll must service them all.	 Any recursive
       event loop that calls an external event loop rather than Tcl_DoOneEvent
       must  reset  the	 service  mode	so  that  all  events get processed in
       Tcl_ServiceAll.	This is done by invoking the Tcl_SetServiceMode proce‐
       dure.   If Tcl_SetServiceMode is passed TCL_SERVICE_NONE, then calls to
       Tcl_ServiceAll will return immediately without processing  any  events.
       If Tcl_SetServiceMode is passed TCL_SERVICE_ALL, then calls to Tcl_Ser‐
       viceAll will behave normally.  Tcl_SetServiceMode returns the  previous
       value  of the service mode, which should be restored when the recursive
       loop exits.  Tcl_GetServiceMode returns the current value of  the  ser‐
       vice mode.

SEE ALSO
       Tcl_CreateFileHandler(3),    Tcl_DeleteFileHandler(3),	 Tcl_Sleep(3),
       Tcl_DoOneEvent(3), Thread(3)

KEYWORDS
       event, notifier, event queue, event sources, file events, timer,	 idle,
       service mode, threads



Tcl				      8.1			   Notifier(3)

Tcl_Preserve(3)		    Tcl Library Procedures	       Tcl_Preserve(3)



______________________________________________________________________________

NAME
       Tcl_Preserve,  Tcl_Release,  Tcl_EventuallyFree - avoid freeing storage
       while it is being used

SYNOPSIS
       #include <tcl.h>

       Tcl_Preserve(clientData)

       Tcl_Release(clientData)

       Tcl_EventuallyFree(clientData, freeProc)

ARGUMENTS
       ClientData clientData (in)	     Token describing structure to  be
					     freed  or reallocated.  Usually a
					     pointer to memory for structure.

       Tcl_FreeProc *freeProc (in)	     Procedure	to  invoke   to	  free
					     clientData.
______________________________________________________________________________

DESCRIPTION
       These  three  procedures help implement a simple reference count mecha‐
       nism for managing storage.  They are designed to solve a problem having
       to  do  with  widget deletion, but are also useful in many other situa‐
       tions.  When a widget is deleted,  its  widget  record  (the  structure
       holding	information  specific  to  the widget) must be returned to the
       storage allocator.  However, it is possible that the widget  record  is
       in  active use by one of the procedures on the stack at the time of the
       deletion.  This can happen, for example, if the command associated with
       a  button  widget causes the button to be destroyed:  an X event causes
       an event-handling C procedure in the button to  be  invoked,  which  in
       turn  causes  the button's associated Tcl command to be executed, which
       in turn causes the button to be deleted, which in turn causes the  but‐
       ton's  widget  record  to be de-allocated.  Unfortunately, when the Tcl
       command returns, the button's event-handling  procedure	will  need  to
       reference  the  button's	 widget	 record.   Because of this, the widget
       record must not be freed as part of the deletion, but must be  retained
       until the event-handling procedure has finished with it.	 In other sit‐
       uations where the widget is deleted, it may be  possible	 to  free  the
       widget record immediately.

       Tcl_Preserve  and Tcl_Release implement short-term reference counts for
       their clientData argument.  The clientData argument identifies  an  ob‐
       ject and usually consists of the address of a structure.	 The reference
       counts guarantee that an object will not be freed until	each  call  to
       Tcl_Preserve  for  the object has been matched by calls to Tcl_Release.
       There may be any number of unmatched Tcl_Preserve calls	in  effect  at
       once.

       Tcl_EventuallyFree  is  invoked to free up its clientData argument.  It
       checks to see if there are unmatched Tcl_Preserve calls for the object.
       If  not, then Tcl_EventuallyFree calls freeProc immediately.  Otherwise
       Tcl_EventuallyFree records the fact that clientData needs eventually to
       be  freed.  When all calls to Tcl_Preserve have been matched with calls
       to Tcl_Release then freeProc will be called by Tcl_Release  to  do  the
       cleanup.

       All  the work of freeing the object is carried out by freeProc.	FreeP‐
       roc must have arguments and result that match the type Tcl_FreeProc:

	      typedef void Tcl_FreeProc(
		      char *blockPtr);

       The blockPtr argument to freeProc will be the same  as  the  clientData
       argument	 to Tcl_EventuallyFree.	 The type of blockPtr (char *) is dif‐
       ferent than the type of the clientData argument	to  Tcl_EventuallyFree
       for historical reasons, but the value is the same.

       When  the  clientData  argument to Tcl_EventuallyFree refers to storage
       allocated and returned by a prior call to Tcl_Alloc,  ckalloc,  or  an‐
       other function of the Tcl library, then the freeProc argument should be
       given the special value of TCL_DYNAMIC.

       This mechanism can be used to solve  the	 problem  described  above  by
       placing	Tcl_Preserve  and  Tcl_Release	calls  around actions that may
       cause undesired storage re-allocation.  The mechanism is intended  only
       for  short-term	use  (i.e. while procedures are pending on the stack);
       it will not work efficiently as a  mechanism  for  long-term  reference
       counts.	 The implementation does not depend in any way on the internal
       structure of the objects being freed;  it keeps the reference counts in
       a separate structure.

SEE ALSO
       Tcl_Interp, Tcl_Alloc

KEYWORDS
       free, reference count, storage



Tcl				      7.5		       Tcl_Preserve(3)

Tcl_SplitList(3)	    Tcl Library Procedures	      Tcl_SplitList(3)



______________________________________________________________________________

NAME
       Tcl_SplitList,	 Tcl_Merge,    Tcl_ScanElement,	   Tcl_ConvertElement,
       Tcl_ScanCountedElement,	Tcl_ConvertCountedElement  -  manipulate   Tcl
       lists

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_SplitList(interp, list, argcPtr, argvPtr)

       char *
       Tcl_Merge(argc, argv)

       int
       Tcl_ScanElement(src, flagsPtr)

       int
       Tcl_ScanCountedElement(src, length, flagsPtr)

       int
       Tcl_ConvertElement(src, dst, flags)

       int
       Tcl_ConvertCountedElement(src, length, dst, flags)

ARGUMENTS
       Tcl_Interp *interp (out)			  Interpreter to use for error
						  reporting.  If NULL, then no
						  error message is left.

       const char *list (in)			  Pointer  to  a  string  with
						  proper list structure.

       int *argcPtr (out)			  Filled in with number of el‐
						  ements in list.

       const char ***argvPtr (out)		  *argvPtr  will  be filled in
						  with the address of an array
						  of  pointers	to the strings
						  that are the extracted  ele‐
						  ments	 of  list.  There will
						  be *argcPtr valid entries in
						  the  array,  followed	 by  a
						  NULL entry.

       int argc (in)				  Number of elements in argv.

       const char *const *argv (in)		  Array of  strings  to	 merge
						  together into a single list.
						  Each string  will  become  a
						  separate   element   of  the
						  list.

       const char *src (in)			  String that is to become  an
						  element of a list.

       int *flagsPtr (in)			  Pointer  to  word to fill in
						  with information about  src.
						  The  value of *flagsPtr must
						  be passed to Tcl_ConvertEle‐
						  ment.

       int length (in)				  Number  of  bytes  in string
						  src.

       char *dst (in)				  Place to copy converted list
						  element.     Must    contain
						  enough  characters  to  hold
						  converted string.

       int flags (in)				  Information  about src. Must
						  be value returned by	previ‐
						  ous call to Tcl_ScanElement,
						  possibly     OR-ed	  with
						  TCL_DONT_USE_BRACES.
______________________________________________________________________________

DESCRIPTION
       These  procedures  may be used to disassemble and reassemble Tcl lists.
       Tcl_SplitList breaks a list up into its constituent elements, returning
       an  array of pointers to the elements using argcPtr and argvPtr.	 While
       extracting the arguments, Tcl_SplitList obeys the usual rules for back‐
       slash  substitutions  and  braces.   The	 area  of memory pointed to by
       *argvPtr is dynamically allocated;  in addition to the array of	point‐
       ers, it also holds copies of all the list elements.  It is the caller's
       responsibility to free up all of this storage.	For  example,  suppose
       that you have called Tcl_SplitList with the following code:

	      int argc, code;
	      char *string;
	      char **argv;
	      ...
	      code = Tcl_SplitList(interp, string, &argc, &argv);

       Then  you  should eventually free the storage with a call like the fol‐
       lowing:

	      Tcl_Free((char *) argv);

       Tcl_SplitList normally returns TCL_OK, which means the  list  was  suc‐
       cessfully  parsed.  If there was a syntax error in list, then TCL_ERROR
       is returned and the interpreter's result will point to an error message
       describing  the	problem (if interp was not NULL).  If TCL_ERROR is re‐
       turned then no memory is allocated and *argvPtr is not modified.

       Tcl_Merge is the inverse of Tcl_SplitList:  it takes  a	collection  of
       strings	given  by argc and argv and generates a result string that has
       proper list structure.  This means that commands like index may be used
       to  extract the original elements again.	 In addition, if the result of
       Tcl_Merge is passed to Tcl_Eval, it will	 be  parsed  into  argc	 words
       whose  values will be the same as the argv strings passed to Tcl_Merge.
       Tcl_Merge will modify the list elements with braces and/or  backslashes
       in  order  to  produce proper Tcl list structure.  The result string is
       dynamically allocated using Tcl_Alloc;  the caller must eventually  re‐
       lease the space using Tcl_Free.

       If the result of Tcl_Merge is passed to Tcl_SplitList, the elements re‐
       turned  by  Tcl_SplitList  will	be  identical  to  those  passed  into
       Tcl_Merge.   However,  the  converse  is not true:  if Tcl_SplitList is
       passed a given string, and the resulting argc and argv  are  passed  to
       Tcl_Merge,  the	resulting  string  may not be the same as the original
       string passed to Tcl_SplitList.	This  is  because  Tcl_Merge  may  use
       backslashes and braces differently than the original string.

       Tcl_ScanElement	and  Tcl_ConvertElement are the procedures that do all
       of the real work of Tcl_Merge.  Tcl_ScanElement scans its src  argument
       and  determines how to use backslashes and braces when converting it to
       a list element.	It returns an overestimate of the number of characters
       required	 to represent src as a list element, and it stores information
       in *flagsPtr that is needed by Tcl_ConvertElement.

       Tcl_ConvertElement is a companion  procedure  to	 Tcl_ScanElement.   It
       does  the  actual  work	of converting a string to a list element.  Its
       flags argument must be the same as the value returned  by  Tcl_ScanEle‐
       ment.  Tcl_ConvertElement writes a proper list element to memory start‐
       ing at *dst and returns a count of the total number of characters writ‐
       ten, which will be no more than the result returned by Tcl_ScanElement.
       Tcl_ConvertElement writes out only the actual list element without  any
       leading	or  trailing  spaces: it is up to the caller to include spaces
       between adjacent list elements.

       Tcl_ConvertElement uses one of two different approaches to  handle  the
       special characters in src.  Wherever possible, it handles special char‐
       acters by surrounding the string with  braces.	This  produces	clean-
       looking output, but cannot be used in some situations, such as when src
       contains unmatched braces.   In	these  situations,  Tcl_ConvertElement
       handles	special characters by generating backslash sequences for them.
       The caller may insist on the second approach by OR-ing the  flag	 value
       returned	 by  Tcl_ScanElement  with TCL_DONT_USE_BRACES.	 Although this
       will produce an uglier result, it is useful in some special situations,
       such  as when Tcl_ConvertElement is being used to generate a portion of
       an argument for a Tcl command.  In  this	 case,	surrounding  src  with
       curly braces would cause the command not to be parsed correctly.

       By  default,  Tcl_ConvertElement	 will  use quoting in its output to be
       sure the first character of an element is not the hash character (“#”.)
       This  is to be sure the first element of any list passed to eval is not
       mis-parsed as the beginning of a comment.  When a list element  is  not
       the  first  element of a list, this quoting is not necessary.  When the
       caller can be sure that the element is not the first element of a list,
       it can disable quoting of the leading hash character by OR-ing the flag
       value returned by Tcl_ScanElement with TCL_DONT_QUOTE_HASH.

       Tcl_ScanCountedElement and Tcl_ConvertCountedElement are	 the  same  as
       Tcl_ScanElement and Tcl_ConvertElement, except the length of string src
       is specified by the length argument, and the string may contain	embed‐
       ded nulls.

SEE ALSO
       Tcl_ListObjGetElements(3)

KEYWORDS
       backslash, convert, element, list, merge, split, strings



Tcl				      8.0		      Tcl_SplitList(3)

Tcl_CreateChannel(3)	    Tcl Library Procedures	  Tcl_CreateChannel(3)



______________________________________________________________________________

NAME
       Tcl_CreateChannel,    Tcl_GetChannelInstanceData,   Tcl_GetChannelType,
       Tcl_GetChannelName,	Tcl_GetChannelHandle,	   Tcl_GetChannelMode,
       Tcl_GetChannelBufferSize,  Tcl_SetChannelBufferSize, Tcl_NotifyChannel,
       Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_Channel‐
       BlockModeProc,  Tcl_ChannelCloseProc,  Tcl_ChannelClose2Proc, Tcl_Chan‐
       nelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc,  Tcl_Channel‐
       WideSeekProc,	 Tcl_ChannelTruncateProc,    Tcl_ChannelSetOptionProc,
       Tcl_ChannelGetOptionProc,    Tcl_ChannelWatchProc,     Tcl_ChannelGetH‐
       andleProc,   Tcl_ChannelFlushProc,   Tcl_ChannelHandlerProc,  Tcl_Chan‐
       nelThreadActionProc,   Tcl_IsChannelShared,    Tcl_IsChannelRegistered,
       Tcl_CutChannel,	      Tcl_SpliceChannel,	Tcl_IsChannelExisting,
       Tcl_ClearChannelHandlers, Tcl_GetChannelThread,	Tcl_ChannelBuffered  -
       procedures for creating and manipulating channels

SYNOPSIS
       #include <tcl.h>

       Tcl_Channel
       Tcl_CreateChannel(typePtr, channelName, instanceData, mask)

       ClientData
       Tcl_GetChannelInstanceData(channel)

       const Tcl_ChannelType *
       Tcl_GetChannelType(channel)

       const char *
       Tcl_GetChannelName(channel)

       int
       Tcl_GetChannelHandle(channel, direction, handlePtr)

       Tcl_ThreadId
       Tcl_GetChannelThread(channel)

       int
       Tcl_GetChannelMode(channel)

       int
       Tcl_GetChannelBufferSize(channel)

       Tcl_SetChannelBufferSize(channel, size)

       Tcl_NotifyChannel(channel, mask)

       int
       Tcl_BadChannelOption(interp, optionName, optionList)

       int
       Tcl_IsChannelShared(channel)

       int
       Tcl_IsChannelRegistered(interp, channel)

       int
       Tcl_IsChannelExisting(channelName)

       void
       Tcl_CutChannel(channel)

       void
       Tcl_SpliceChannel(channel)

       void
       Tcl_ClearChannelHandlers(channel)

       int
       Tcl_ChannelBuffered(channel)

       const char *
       Tcl_ChannelName(typePtr)

       Tcl_ChannelTypeVersion
       Tcl_ChannelVersion(typePtr)

       Tcl_DriverBlockModeProc *
       Tcl_ChannelBlockModeProc(typePtr)

       Tcl_DriverCloseProc *
       Tcl_ChannelCloseProc(typePtr)

       Tcl_DriverClose2Proc *
       Tcl_ChannelClose2Proc(typePtr)

       Tcl_DriverInputProc *
       Tcl_ChannelInputProc(typePtr)

       Tcl_DriverOutputProc *
       Tcl_ChannelOutputProc(typePtr)

       Tcl_DriverSeekProc *
       Tcl_ChannelSeekProc(typePtr)

       Tcl_DriverWideSeekProc *
       Tcl_ChannelWideSeekProc(typePtr)

       Tcl_DriverThreadActionProc *
       Tcl_ChannelThreadActionProc(typePtr)

       Tcl_DriverTruncateProc *
       Tcl_ChannelTruncateProc(typePtr)

       Tcl_DriverSetOptionProc *
       Tcl_ChannelSetOptionProc(typePtr)

       Tcl_DriverGetOptionProc *
       Tcl_ChannelGetOptionProc(typePtr)

       Tcl_DriverWatchProc *
       Tcl_ChannelWatchProc(typePtr)

       Tcl_DriverGetHandleProc *
       Tcl_ChannelGetHandleProc(typePtr)

       Tcl_DriverFlushProc *
       Tcl_ChannelFlushProc(typePtr)

       Tcl_DriverHandlerProc *
       Tcl_ChannelHandlerProc(typePtr)


ARGUMENTS
       const Tcl_ChannelType *typePtr (in)		Points	to a structure
							containing   the   ad‐
							dresses	 of procedures
							that can be called  to
							perform	 I/O and other
							functions on the chan‐
							nel.

       const char *channelName (in)			The name of this chan‐
							nel,  such  as	file3;
							must  not be in use by
							any other channel. Can
							be NULL, in which case
							the channel is created
							without a name. If the
							created channel is as‐
							signed	to  one of the
							standard      channels
							(stdin,	   stdout   or
							stderr), the  assigned
							channel	 name  will be
							the name of the	 stan‐
							dard channel.

       ClientData instanceData (in)			Arbitrary     one-word
							value to be associated
							with   this   channel.
							This value  is	passed
							to procedures in type‐
							Ptr when they are  in‐
							voked.

       int mask (in)					OR-ed  combination  of
							TCL_READABLE	   and
							TCL_WRITABLE  to indi‐
							cate whether a channel
							is     readable	   and
							writable.

       Tcl_Channel channel (in)				The channel to operate
							on.

       int direction (in)				TCL_READABLE means the
							input	 handle	    is
							wanted;	  TCL_WRITABLE
							means the output  han‐
							dle is wanted.

       ClientData *handlePtr (out)			Points to the location
							where the desired  OS-
							specific handle should
							be stored.

       int size (in)					The size, in bytes, of
							buffers to allocate in
							this channel.

       int mask (in)					An  OR-ed  combination
							of	 TCL_READABLE,
							TCL_WRITABLE	   and
							TCL_EXCEPTION that in‐
							dicates	 events	  that
							have  occurred on this
							channel.

       Tcl_Interp *interp (in)				Current	  interpreter.
							(can be NULL)

       const char *optionName (in)			Name  of  the  invalid
							option.

       const char *optionList (in)			Specific options  list
							(space	     separated
							words, without “-”) to
							append to the standard
							generic options	 list.
							Can    be   NULL   for
							generic options	 error
							message only.
______________________________________________________________________________

DESCRIPTION
       Tcl  uses a two-layered channel architecture. It provides a generic up‐
       per layer to enable C and Tcl programs to perform input and output  us‐
       ing  the	 same  APIs  for a variety of files, devices, sockets etc. The
       generic C APIs are described in the manual entry for  Tcl_OpenFileChan‐
       nel.

       The lower layer provides type-specific channel drivers for each type of
       device supported on each platform.  This manual entry describes	the  C
       APIs  used  to  communicate between the generic layer and the type-spe‐
       cific channel drivers.  It also explains how new types of channels  can
       be added by providing new channel drivers.

       Channel	drivers consist of a number of components: First, each channel
       driver provides a  Tcl_ChannelType  structure  containing  pointers  to
       functions implementing the various operations used by the generic layer
       to communicate with the channel driver. The  Tcl_ChannelType  structure
       and  the	 functions  referenced	by  it	are  described	in the section
       TCL_CHANNELTYPE, below.

       Second, channel drivers usually provide a Tcl  command  to  create  in‐
       stances of that type of channel. For example, the Tcl open command cre‐
       ates channels that use the file and command channel  drivers,  and  the
       Tcl  socket  command  creates channels that use TCP sockets for network
       communication.

       Third, a channel driver optionally provides a C function to open	 chan‐
       nel  instances  of  that type. For example, Tcl_OpenFileChannel opens a
       channel that uses the file channel driver, and Tcl_OpenTcpClient	 opens
       a channel that uses the TCP network protocol.  These creation functions
       typically use Tcl_CreateChannel internally to open the channel.

       To add a new type of channel you must implement a C API or a  Tcl  com‐
       mand  that  opens  a  channel by invoking Tcl_CreateChannel.  When your
       driver calls Tcl_CreateChannel it passes in a Tcl_ChannelType structure
       describing  the	driver's  I/O procedures.  The generic layer will then
       invoke the functions referenced in that structure to perform operations
       on the channel.

       Tcl_CreateChannel opens a new channel and associates the supplied type‐
       Ptr and instanceData with it. The channel is opened in the  mode	 indi‐
       cated  by  mask.	 For a discussion of channel drivers, their operations
       and the Tcl_ChannelType structure, see the section TCL_CHANNELTYPE, be‐
       low.

       Tcl_CreateChannel  interacts  with the code managing the standard chan‐
       nels. Once a standard channel was initialized either through a call  to
       Tcl_GetStdChannel  or a call to Tcl_SetStdChannel closing this standard
       channel will cause the next call to Tcl_CreateChannel to make  the  new
       channel	the  new  standard channel too. See Tcl_StandardChannels for a
       general treatise about standard channels and the behavior  of  the  Tcl
       library with regard to them.

       Tcl_GetChannelInstanceData  returns  the	 instance data associated with
       the channel in channel. This is the same as the	instanceData  argument
       in the call to Tcl_CreateChannel that created this channel.

       Tcl_GetChannelType  returns  a pointer to the Tcl_ChannelType structure
       used by the channel in the channel argument. This is the	 same  as  the
       typePtr	argument  in  the  call to Tcl_CreateChannel that created this
       channel.

       Tcl_GetChannelName returns a string containing the name associated with
       the  channel,  or NULL if the channelName argument to Tcl_CreateChannel
       was NULL.

       Tcl_GetChannelHandle places the OS-specific  device  handle  associated
       with  channel for the given direction in the location specified by han‐
       dlePtr and returns TCL_OK.  If the channel does not have a device  han‐
       dle  for	 the  specified direction, then TCL_ERROR is returned instead.
       Different channel drivers will return different types of handle.	 Refer
       to  the manual entries for each driver to determine what type of handle
       is returned.

       Tcl_GetChannelThread returns the id of the  thread  currently  managing
       the  specified  channel. This allows channel drivers to send their file
       events to the correct event queue even for a multi-threaded core.

       Tcl_GetChannelMode returns an OR-ed  combination	 of  TCL_READABLE  and
       TCL_WRITABLE, indicating whether the channel is open for input and out‐
       put.

       Tcl_GetChannelBufferSize returns the size, in bytes, of	buffers	 allo‐
       cated  to store input or output in channel. If the value was not set by
       a previous call to Tcl_SetChannelBufferSize, described below, then  the
       default value of 4096 is returned.

       Tcl_SetChannelBufferSize	 sets the size, in bytes, of buffers that will
       be allocated in subsequent operations on the channel to store input  or
       output. The size argument should be between one and one million, allow‐
       ing buffers of one byte to one million bytes. If size is	 outside  this
       range, Tcl_SetChannelBufferSize sets the buffer size to 4096.

       Tcl_NotifyChannel  is  called  by  a  channel driver to indicate to the
       generic layer that the events specified by mask have  occurred  on  the
       channel.	  Channel  drivers  are responsible for invoking this function
       whenever the channel handlers need to be called	for  the  channel  (or
       other  pending  tasks  like  a  write  flush should be performed).  See
       WATCHPROC below for more details.

       Tcl_BadChannelOption is called from driver  specific  setOptionProc  or
       getOptionProc to generate a complete error message.

       Tcl_ChannelBuffered  returns  the  number  of  bytes of input currently
       buffered in the internal buffer (push back area) of the channel itself.
       It  does not report about the data in the overall buffers for the stack
       of channels the supplied channel is part of.

       Tcl_IsChannelShared checks the refcount of the  specified  channel  and
       returns whether the channel was shared among multiple interpreters (re‐
       sult == 1) or not (result == 0).

       Tcl_IsChannelRegistered checks whether the specified channel is	regis‐
       tered in the given interpreter (result == 1) or not (result == 0).

       Tcl_IsChannelExisting  checks whether a channel with the specified name
       is registered in the (thread)-global list of all channels (result == 1)
       or not (result == 0).

       Tcl_CutChannel  removes	the  specified channel from the (thread)global
       list of all channels (of the current thread).  Application to a channel
       still registered in some interpreter is not allowed.  Also notifies the
       driver if the  Tcl_ChannelType  version	is  TCL_CHANNEL_VERSION_4  (or
       higher), and Tcl_DriverThreadActionProc is defined for it.

       Tcl_SpliceChannel adds the specified channel to the (thread)global list
       of all channels (of the current thread).	 Application to a channel reg‐
       istered	in  some interpreter is not allowed.  Also notifies the driver
       if the Tcl_ChannelType version is  TCL_CHANNEL_VERSION_4	 (or  higher),
       and Tcl_DriverThreadActionProc is defined for it.

       Tcl_ClearChannelHandlers removes all channel handlers and event scripts
       associated with the specified channel, thus  shutting  down  all	 event
       processing for this channel.

TCL_CHANNELTYPE
       A  channel  driver  provides  a Tcl_ChannelType structure that contains
       pointers to functions that implement the various operations on a	 chan‐
       nel;  these operations are invoked as needed by the generic layer.  The
       structure was versioned starting in Tcl 8.3.2/8.4 to correct a  problem
       with  stacked channel drivers.  See the OLD CHANNEL TYPES section below
       for details about the old structure.

       The Tcl_ChannelType structure contains the following fields:

	      typedef struct Tcl_ChannelType {
		      const char *typeName;
		      Tcl_ChannelTypeVersion version;
		      Tcl_DriverCloseProc *closeProc;
		      Tcl_DriverInputProc *inputProc;
		      Tcl_DriverOutputProc *outputProc;
		      Tcl_DriverSeekProc *seekProc;
		      Tcl_DriverSetOptionProc *setOptionProc;
		      Tcl_DriverGetOptionProc *getOptionProc;
		      Tcl_DriverWatchProc *watchProc;
		      Tcl_DriverGetHandleProc *getHandleProc;
		      Tcl_DriverClose2Proc *close2Proc;
		      Tcl_DriverBlockModeProc *blockModeProc;
		      Tcl_DriverFlushProc *flushProc;
		      Tcl_DriverHandlerProc *handlerProc;
		      Tcl_DriverWideSeekProc *wideSeekProc;
		      Tcl_DriverThreadActionProc *threadActionProc;
		      Tcl_DriverTruncateProc *truncateProc;
	      } Tcl_ChannelType;

       It is not necessary to provide implementations for all  channel	opera‐
       tions.  Those which are not necessary may be set to NULL in the struct:
       blockModeProc, seekProc, setOptionProc,	getOptionProc,	getHandleProc,
       and  close2Proc,	 in  addition to flushProc, handlerProc, threadAction‐
       Proc, and truncateProc.	Other functions that cannot be implemented  in
       a meaningful way should return EINVAL when called, to indicate that the
       operations  they	 represent  are	 not   available.   Also   note	  that
       wideSeekProc can be NULL if seekProc is.

       The  user  should  only use the above structure for Tcl_ChannelType in‐
       stantiation.  When referencing fields in a  Tcl_ChannelType  structure,
       the  following functions should be used to obtain the values: Tcl_Chan‐
       nelName,	 Tcl_ChannelVersion,  Tcl_ChannelBlockModeProc,	  Tcl_Channel‐
       CloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOut‐
       putProc,	  Tcl_ChannelSeekProc,	 Tcl_ChannelWideSeekProc,    Tcl_Chan‐
       nelThreadActionProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc,
       Tcl_ChannelGetOptionProc,    Tcl_ChannelWatchProc,     Tcl_ChannelGetH‐
       andleProc, Tcl_ChannelFlushProc, or Tcl_ChannelHandlerProc.

       The change to the structures was made in such a way that standard chan‐
       nel types are binary  compatible.   However,  channel  types  that  use
       stacked channels (i.e. TLS, Trf) have new versions to correspond to the
       above change since the previous code for stacked channels had problems.

   TYPENAME
       The typeName field contains a null-terminated  string  that  identifies
       the  type  of  the  device  implemented	by  this driver, e.g.  file or
       socket.

       This value can be  retrieved  with  Tcl_ChannelName,  which  returns  a
       pointer to the string.

   VERSION
       The  version  field  should be set to the version of the structure that
       you  require.  TCL_CHANNEL_VERSION_2  is	  the	minimum	  recommended.
       TCL_CHANNEL_VERSION_3  must  be set to specify the wideSeekProc member.
       TCL_CHANNEL_VERSION_4 must be set to specify the threadActionProc  mem‐
       ber  (includes  wideSeekProc).	TCL_CHANNEL_VERSION_5  must  be set to
       specify the truncateProc members (includes wideSeekProc	and  threadAc‐
       tionProc).  If it is not set to any of these, then this Tcl_ChannelType
       is assumed to have the original structure.  See OLD CHANNEL  TYPES  for
       more details.  While Tcl will recognize and function with either struc‐
       tures, stacked channels must be of at  least  TCL_CHANNEL_VERSION_2  to
       function correctly.

       This  value can be retrieved with Tcl_ChannelVersion, which returns one
       of TCL_CHANNEL_VERSION_5, TCL_CHANNEL_VERSION_4, TCL_CHANNEL_VERSION_3,
       TCL_CHANNEL_VERSION_2 or TCL_CHANNEL_VERSION_1.

   BLOCKMODEPROC
       The  blockModeProc  field  contains the address of a function called by
       the generic layer to set blocking and nonblocking mode on  the  device.
       BlockModeProc should match the following prototype:

	      typedef int Tcl_DriverBlockModeProc(
		      ClientData instanceData,
		      int mode);

       The  instanceData  is the same as the value passed to Tcl_CreateChannel
       when  this  channel  was	 created.   The	 mode	argument   is	either
       TCL_MODE_BLOCKING or TCL_MODE_NONBLOCKING to set the device into block‐
       ing or nonblocking mode. The function should return zero if the	opera‐
       tion  was  successful,  or  a nonzero POSIX error code if the operation
       failed.

       If the operation is successful, the function can	 modify	 the  supplied
       instanceData to record that the channel entered blocking or nonblocking
       mode and to implement the blocking or nonblocking behavior.   For  some
       device  types, the blocking and nonblocking behavior can be implemented
       by the underlying operating system; for other device types, the	behav‐
       ior must be emulated in the channel driver.

       This  value  can	 be retrieved with Tcl_ChannelBlockModeProc, which re‐
       turns a pointer to the function.

       A channel driver not supplying a blockModeProc has  to  be  very,  very
       careful.	 It  has to tell the generic layer exactly which blocking mode
       is acceptable to it, and should this also document for the user so that
       the  blocking  mode  of	the  channel is not changed to an unacceptable
       value. Any confusion here may lead the interpreter into a (spurious and
       difficult to find) deadlock.

   CLOSEPROC AND CLOSE2PROC
       The  closeProc  field  contains the address of a function called by the
       generic layer to clean up driver-related information when  the  channel
       is closed. CloseProc must match the following prototype:

	      typedef int Tcl_DriverCloseProc(
		      ClientData instanceData,
		      Tcl_Interp *interp);

       The instanceData argument is the same as the value provided to Tcl_Cre‐
       ateChannel when the channel was created. The  function  should  release
       any  storage  maintained	 by  the  channel driver for this channel, and
       close the input and output devices encapsulated by  this	 channel.  All
       queued output will have been flushed to the device before this function
       is called, and no further driver operations will be invoked on this in‐
       stance  after calling the closeProc. If the close operation is success‐
       ful, the procedure should return zero; otherwise	 it  should  return  a
       nonzero POSIX error code. In addition, if an error occurs and interp is
       not NULL, the procedure should store an error  message  in  the	inter‐
       preter's result.

       Alternatively,  channels	 that support closing the read and write sides
       independently may set closeProc to TCL_CLOSE2PROC and set close2Proc to
       the address of a function that matches the following prototype:

	      typedef int Tcl_DriverClose2Proc(
		      ClientData instanceData,
		      Tcl_Interp *interp,
		      int flags);

       The close2Proc will be called with flags set to an OR'ed combination of
       TCL_CLOSE_READ or TCL_CLOSE_WRITE to indicate that  the	driver	should
       close  the  read	 and/or write side of the channel.  The channel driver
       may be invoked to perform additional operations on  the	channel	 after
       close2Proc  is  called  to  close one or both sides of the channel.  If
       flags is 0 (zero), the driver should close the channel  in  the	manner
       described  above	 for closeProc.	 No further operations will be invoked
       on this instance after close2Proc is called with all flags cleared.  In
       all  cases, the close2Proc function should return zero if the close op‐
       eration was successful; otherwise it should return a nonzero POSIX  er‐
       ror  code.  In addition, if an error occurs and interp is not NULL, the
       procedure should store an error message in the interpreter's result.

       The closeProc and close2Proc values can be retrieved with  Tcl_Channel‐
       CloseProc  or  Tcl_ChannelClose2Proc, which return a pointer to the re‐
       spective function.

   INPUTPROC
       The inputProc field contains the address of a function  called  by  the
       generic	layer  to read data from the file or device and store it in an
       internal buffer. InputProc must match the following prototype:

	      typedef int Tcl_DriverInputProc(
		      ClientData instanceData,
		      char *buf,
		      int bufSize,
		      int *errorCodePtr);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       the  channel was created.  The buf argument points to an array of bytes
       in which to store input from the device, and the bufSize argument indi‐
       cates how many bytes are available at buf.

       The errorCodePtr argument points to an integer variable provided by the
       generic layer. If an error occurs, the function should set the variable
       to a POSIX error code that identifies the error that occurred.

       The function should read data from the input device encapsulated by the
       channel and store it at buf.  On success, the function should return  a
       nonnegative  integer indicating how many bytes were read from the input
       device and stored at buf. On error, the function should return  -1.  If
       an  error  occurs  after	 some data has been read from the device, that
       data is lost.

       If inputProc can determine that the input device has some  data	avail‐
       able  but  less	than  requested	 by the bufSize argument, the function
       should only attempt to read as much data as  is	available  and	return
       without	blocking. If the input device has no data available whatsoever
       and the channel is in nonblocking mode, the function should  return  an
       EAGAIN  error. If the input device has no data available whatsoever and
       the channel is in blocking mode, the  function  should  block  for  the
       shortest possible time until at least one byte of data can be read from
       the device; then, it should return as much data as it can read  without
       blocking.

       This  value can be retrieved with Tcl_ChannelInputProc, which returns a
       pointer to the function.

   OUTPUTPROC
       The outputProc field contains the address of a function called  by  the
       generic	layer  to  transfer data from an internal buffer to the output
       device.	OutputProc must match the following prototype:

	      typedef int Tcl_DriverOutputProc(
		      ClientData instanceData,
		      const char *buf,
		      int toWrite,
		      int *errorCodePtr);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       the channel was created. The buf argument contains an array of bytes to
       be written to the device, and the toWrite argument indicates  how  many
       bytes are to be written from the buf argument.

       The errorCodePtr argument points to an integer variable provided by the
       generic layer. If an error occurs, the function should set  this	 vari‐
       able to a POSIX error code that identifies the error.

       The function should write the data at buf to the output device encapsu‐
       lated by the channel. On success, the function should return a nonnega‐
       tive  integer  indicating how many bytes were written to the output de‐
       vice.  The return value is normally the same as	toWrite,  but  may  be
       less  in some cases such as if the output operation is interrupted by a
       signal. If an error occurs the function should return -1.  In  case  of
       error, some data may have been written to the device.

       If the channel is nonblocking and the output device is unable to absorb
       any data whatsoever, the function should return -1 with an EAGAIN error
       without writing any data.

       This value can be retrieved with Tcl_ChannelOutputProc, which returns a
       pointer to the function.

   SEEKPROC AND WIDESEEKPROC
       The seekProc field contains the address of a  function  called  by  the
       generic	layer  to  move	 the access point at which subsequent input or
       output operations will be applied. SeekProc must	 match	the  following
       prototype:

	      typedef int Tcl_DriverSeekProc(
		      ClientData instanceData,
		      long offset,
		      int seekMode,
		      int *errorCodePtr);

       The instanceData argument is the same as the value given to Tcl_Create‐
       Channel when this channel was created.  Offset and  seekMode  have  the
       same meaning as for the Tcl_Seek procedure (described in the manual en‐
       try for Tcl_OpenFileChannel).

       The errorCodePtr argument points to an integer variable provided by the
       generic	layer for returning errno values from the function.  The func‐
       tion should set this variable to a POSIX error code if an error occurs.
       The function should store an EINVAL error code if the channel type does
       not implement seeking.

       The return value is the new access point or -1 in case of error. If  an
       error occurred, the function should not move the access point.

       If  there is a non-NULL seekProc field, the wideSeekProc field may con‐
       tain the address of an alternative function to use which	 handles  wide
       (i.e.  larger  than  32-bit)  offsets,  so  allowing seeks within files
       larger than 2GB.	 The wideSeekProc will be called in preference to  the
       seekProc,  but  both  must  be  defined if the wideSeekProc is defined.
       WideSeekProc must match the following prototype:

	      typedef Tcl_WideInt Tcl_DriverWideSeekProc(
		      ClientData instanceData,
		      Tcl_WideInt offset,
		      int seekMode,
		      int *errorCodePtr);

       The arguments and return values mean the same thing  as	with  seekProc
       above,  except that the type of offsets and the return type are differ‐
       ent.

       The seekProc value can be retrieved with Tcl_ChannelSeekProc, which re‐
       turns  a pointer to the function, and similarly the wideSeekProc can be
       retrieved with Tcl_ChannelWideSeekProc.

   SETOPTIONPROC
       The setOptionProc field contains the address of a  function  called  by
       the  generic  layer to set a channel type specific option on a channel.
       setOptionProc must match the following prototype:

	      typedef int Tcl_DriverSetOptionProc(
		      ClientData instanceData,
		      Tcl_Interp *interp,
		      const char *optionName,
		      const char *newValue);

       optionName is the name of an option to set, and	newValue  is  the  new
       value for that option, as a string. The instanceData is the same as the
       value given to Tcl_CreateChannel when this  channel  was	 created.  The
       function should do whatever channel type specific action is required to
       implement the new value of the option.

       Some options are handled by the generic code and this function is never
       called to set them, e.g. -blockmode. Other options are specific to each
       channel type and the setOptionProc procedure of the channel driver will
       get  called  to	implement  them.  The setOptionProc field can be NULL,
       which indicates that this channel type supports no  type	 specific  op‐
       tions.

       If  the	option	value  is  successfully modified to the new value, the
       function returns TCL_OK.	 It should call Tcl_BadChannelOption which it‐
       self  returns TCL_ERROR if the optionName is unrecognized.  If newValue
       specifies a value for the option that is not supported or if  a	system
       call  error  occurs,  the function should leave an error message in the
       result of interp if interp is not NULL. The function should  also  call
       Tcl_SetErrno to store an appropriate POSIX error code.

       This  value  can	 be retrieved with Tcl_ChannelSetOptionProc, which re‐
       turns a pointer to the function.

   GETOPTIONPROC
       The getOptionProc field contains the address of a  function  called  by
       the generic layer to get the value of a channel type specific option on
       a channel. getOptionProc must match the following prototype:

	      typedef int Tcl_DriverGetOptionProc(
		      ClientData instanceData,
		      Tcl_Interp *interp,
		      const char *optionName,
		      Tcl_DString *optionValue);

       OptionName is the name of an option supported by this type of  channel.
       If  the option name is not NULL, the function stores its current value,
       as a string, in the Tcl dynamic string optionValue.  If	optionName  is
       NULL,  the  function  stores  in optionValue an alternating list of all
       supported options and their current values.  On success,	 the  function
       returns	TCL_OK.	  It should call Tcl_BadChannelOption which itself re‐
       turns TCL_ERROR if the optionName is unrecognized. If a system call er‐
       ror occurs, the function should leave an error message in the result of
       interp if interp is not NULL. The function should also call  Tcl_SetEr‐
       rno to store an appropriate POSIX error code.

       Some options are handled by the generic code and this function is never
       called to retrieve their value, e.g. -blockmode. Other options are spe‐
       cific to each channel type and the getOptionProc procedure of the chan‐
       nel driver will get called to implement them. The  getOptionProc	 field
       can  be	NULL,  which indicates that this channel type supports no type
       specific options.

       This value can be retrieved with	 Tcl_ChannelGetOptionProc,  which  re‐
       turns a pointer to the function.

   WATCHPROC
       The  watchProc  field  contains the address of a function called by the
       generic layer to initialize the event notification mechanism to	notice
       events of interest on this channel.  WatchProc should match the follow‐
       ing prototype:

	      typedef void Tcl_DriverWatchProc(
		      ClientData instanceData,
		      int mask);

       The instanceData is the same as the value passed	 to  Tcl_CreateChannel
       when  this  channel was created. The mask argument is an OR-ed combina‐
       tion of TCL_READABLE,  TCL_WRITABLE  and	 TCL_EXCEPTION;	 it  indicates
       events the caller is interested in noticing on this channel.

       The  function  should initialize device type specific mechanisms to no‐
       tice when an event of interest is present on the channel.  When one  or
       more of the designated events occurs on the channel, the channel driver
       is responsible for calling  Tcl_NotifyChannel  to  inform  the  generic
       channel	module.	 The driver should take care not to starve other chan‐
       nel drivers or sources of callbacks by invoking	Tcl_NotifyChannel  too
       frequently.   Fairness  can  be insured by using the Tcl event queue to
       allow the channel event to be scheduled in sequence with other  events.
       See  the	 description  of Tcl_QueueEvent for details on how to queue an
       event.

       This value can be retrieved with Tcl_ChannelWatchProc, which returns  a
       pointer to the function.

   GETHANDLEPROC
       The  getHandleProc  field  contains the address of a function called by
       the generic layer to retrieve a device-specific handle from  the	 chan‐
       nel.  GetHandleProc should match the following prototype:

	      typedef int Tcl_DriverGetHandleProc(
		      ClientData instanceData,
		      int direction,
		      ClientData *handlePtr);

       InstanceData  is the same as the value passed to Tcl_CreateChannel when
       this channel was created. The direction argument is either TCL_READABLE
       to  retrieve the handle used for input, or TCL_WRITABLE to retrieve the
       handle used for output.

       If the channel implementation has device-specific handles, the function
       should retrieve the appropriate handle associated with the channel, ac‐
       cording the direction argument.	The handle should be stored in the lo‐
       cation referred to by handlePtr, and TCL_OK should be returned.	If the
       channel is not open for the specified direction, or if the channel  im‐
       plementation  does  not	use device handles, the function should return
       TCL_ERROR.

       This value can be retrieved with	 Tcl_ChannelGetHandleProc,  which  re‐
       turns a pointer to the function.

   FLUSHPROC
       The flushProc field is currently reserved for future use.  It should be
       set to NULL.  FlushProc should match the following prototype:

	      typedef int Tcl_DriverFlushProc(
		      ClientData instanceData);

       This value can be retrieved with Tcl_ChannelFlushProc, which returns  a
       pointer to the function.

   HANDLERPROC
       The  handlerProc field contains the address of a function called by the
       generic layer to notify the channel that an event occurred.  It	should
       be  defined  for	 stacked  channel  drivers that wish to be notified of
       events that occur on the	 underlying  (stacked)	channel.   HandlerProc
       should match the following prototype:

	      typedef int Tcl_DriverHandlerProc(
		      ClientData instanceData,
		      int interestMask);

       InstanceData  is the same as the value passed to Tcl_CreateChannel when
       this channel was created.  The interestMask is an OR-ed combination  of
       TCL_READABLE  or TCL_WRITABLE; it indicates what type of event occurred
       on this channel.

       This value can be retrieved with Tcl_ChannelHandlerProc, which  returns
       a pointer to the function.


   THREADACTIONPROC
       The  threadActionProc field contains the address of the function called
       by the generic layer when a channel is created,	closed,	 or  going  to
       move  to a different thread, i.e. whenever thread-specific driver state
       might have to initialized or updated.  It  can  be  NULL.   The	action
       TCL_CHANNEL_THREAD_REMOVE  is  used to notify the driver that it should
       update or remove any thread-specific data it might be  maintaining  for
       the channel.

       The  action TCL_CHANNEL_THREAD_INSERT is used to notify the driver that
       it should update or initialize any thread-specific  data	 it  might  be
       maintaining using the calling thread as the associate. See Tcl_CutChan‐
       nel and Tcl_SpliceChannel for more detail.

	      typedef void Tcl_DriverThreadActionProc(
		      ClientData instanceData,
		      int action);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       this channel was created.

       These  values  can be retrieved with Tcl_ChannelThreadActionProc, which
       returns a pointer to the function.

   TRUNCATEPROC
       The truncateProc field contains the address of the function  called  by
       the generic layer when a channel is truncated to some length. It can be
       NULL.

	      typedef int Tcl_DriverTruncateProc(
		      ClientData instanceData,
		      Tcl_WideInt length);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       this  channel was created, and length is the new length of the underly‐
       ing file, which should not be negative. The result should be 0 on  suc‐
       cess or an errno code (suitable for use with Tcl_SetErrno) on failure.

       These  values  can be retrieved with Tcl_ChannelTruncateProc, which re‐
       turns a pointer to the function.

TCL_BADCHANNELOPTION
       This procedure generates a “bad option” error message in an  (optional)
       interpreter.  It is used by channel drivers when an invalid Set/Get op‐
       tion is requested. Its purpose is to concatenate	 the  generic  options
       list  to the specific ones and factorize the generic options error mes‐
       sage string.

       It always returns TCL_ERROR

       An error message is generated in interp's result value to indicate that
       a command was invoked with a bad option.	 The message has the form
		  bad option "blah": should be one of
		  <...generic options...>+<...specific options...>
       so you get for instance:
		  bad option "-blah": should be one of -blocking,
		  -buffering, -buffersize, -eofchar, -translation,
		  -peername, or -sockname
       when called with optionList equal to “peername sockname”

       “blah”  is  the optionName argument and “<specific options>” is a space
       separated list of specific option words.	 The function takes good  care
       of  inserting minus signs before each option, commas after, and an “or”
       before the last option.

OLD CHANNEL TYPES
       The original (8.3.1 and below) Tcl_ChannelType structure	 contains  the
       following fields:

	      typedef struct Tcl_ChannelType {
		  const char *typeName;
		  Tcl_DriverBlockModeProc *blockModeProc;
		  Tcl_DriverCloseProc *closeProc;
		  Tcl_DriverInputProc *inputProc;
		  Tcl_DriverOutputProc *outputProc;
		  Tcl_DriverSeekProc *seekProc;
		  Tcl_DriverSetOptionProc *setOptionProc;
		  Tcl_DriverGetOptionProc *getOptionProc;
		  Tcl_DriverWatchProc *watchProc;
		  Tcl_DriverGetHandleProc *getHandleProc;
		  Tcl_DriverClose2Proc *close2Proc;
	      } Tcl_ChannelType;

       It  is  still possible to create channel with the above structure.  The
       internal channel code will determine the version.  It is imperative  to
       use  the	 new  Tcl_ChannelType  structure if you are creating a stacked
       channel driver, due to problems with the earlier stacked channel imple‐
       mentation (in 8.2.0 to 8.3.1).

       Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part of
       the 8.4 development cycle) the Tcl_ChannelType structure contained  the
       following fields:

	      typedef struct Tcl_ChannelType {
		  const char *typeName;
		  Tcl_ChannelTypeVersion version;
		  Tcl_DriverCloseProc *closeProc;
		  Tcl_DriverInputProc *inputProc;
		  Tcl_DriverOutputProc *outputProc;
		  Tcl_DriverSeekProc *seekProc;
		  Tcl_DriverSetOptionProc *setOptionProc;
		  Tcl_DriverGetOptionProc *getOptionProc;
		  Tcl_DriverWatchProc *watchProc;
		  Tcl_DriverGetHandleProc *getHandleProc;
		  Tcl_DriverClose2Proc *close2Proc;
		  Tcl_DriverBlockModeProc *blockModeProc;
		  Tcl_DriverFlushProc *flushProc;
		  Tcl_DriverHandlerProc *handlerProc;
		  Tcl_DriverTruncateProc *truncateProc;
	      } Tcl_ChannelType;

       When  the  above structure is registered as a channel type, the version
       field should always be TCL_CHANNEL_VERSION_2.

SEE ALSO
       Tcl_Close(3),	     Tcl_OpenFileChannel(3),	      Tcl_SetErrno(3),
       Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)

KEYWORDS
       blocking, channel driver, channel registration, channel type, nonblock‐
       ing



Tcl				      8.4		  Tcl_CreateChannel(3)

Tcl_ObjType(3)		    Tcl Library Procedures		Tcl_ObjType(3)



______________________________________________________________________________

NAME
       Tcl_RegisterObjType,  Tcl_GetObjType,  Tcl_AppendAllObjTypes,  Tcl_Con‐
       vertToType  - manipulate Tcl value types

SYNOPSIS
       #include <tcl.h>

       Tcl_RegisterObjType(typePtr)

       const Tcl_ObjType *
       Tcl_GetObjType(typeName)

       int
       Tcl_AppendAllObjTypes(interp, objPtr)

       int
       Tcl_ConvertToType(interp, objPtr, typePtr)

ARGUMENTS
       const Tcl_ObjType *typePtr (in)	  Points to the	 structure  containing
					  information	about  the  Tcl	 value
					  type.	 This storage must  live  for‐
					  ever,	 typically by being statically
					  allocated.

       const char *typeName (in)	  The name of a Tcl  value  type  that
					  Tcl_GetObjType should look up.

       Tcl_Interp *interp (in)		  Interpreter to use for error report‐
					  ing.

       Tcl_Obj *objPtr (in)		  For	Tcl_AppendAllObjTypes,	  this
					  points  to  the  value onto which it
					  appends the name of each value  type
					  as a list element.  For Tcl_Convert‐
					  ToType, this points to a value  that
					  must	have been the result of a pre‐
					  vious call to Tcl_NewObj.
______________________________________________________________________________


DESCRIPTION
       The procedures in this man page manage Tcl value types  (sometimes  re‐
       ferred  to  as  object  types  or Tcl_ObjTypes for historical reasons).
       They are used to register new value types, look	up  types,  and	 force
       conversions from one type to another.

       Tcl_RegisterObjType  registers a new Tcl value type in the table of all
       value types that Tcl_GetObjType can look up by name.  There  are	 other
       value  types  supported by Tcl as well, which Tcl chooses not to regis‐
       ter.  Extensions can likewise choose to register the value  types  they
       create  or not.	The argument typePtr points to a Tcl_ObjType structure
       that describes the new type by giving its name and by supplying	point‐
       ers  to four procedures that implement the type.	 If the type table al‐
       ready contains a type with the same name as in typePtr, it is  replaced
       with  the new type.  The Tcl_ObjType structure is described in the sec‐
       tion THE TCL_OBJTYPE STRUCTURE below.

       Tcl_GetObjType returns a pointer to  the	 registered  Tcl_ObjType  with
       name  typeName.	 It  returns  NULL if no type with that name is regis‐
       tered.

       Tcl_AppendAllObjTypes appends the name of each registered value type as
       a  list	element	 onto  the Tcl value referenced by objPtr.  The return
       value is TCL_OK unless there was an error converting objPtr to  a  list
       value; in that case TCL_ERROR is returned.

       Tcl_ConvertToType  converts  a value from one type to another if possi‐
       ble.  It creates a new internal representation for  objPtr  appropriate
       for  the	 target type typePtr and sets its typePtr member as determined
       by calling the typePtr->setFromAnyProc routine.	Any internal represen‐
       tation  for objPtr's old type is freed.	If an error occurs during con‐
       version, it returns TCL_ERROR and leaves an error message in the result
       value  for interp unless interp is NULL.	 Otherwise, it returns TCL_OK.
       Passing a NULL interp allows this  procedure  to	 be  used  as  a  test
       whether the conversion can be done (and in fact was done).

       In  many	 cases,	 the  typePtr->setFromAnyProc  routine	will  set  ob‐
       jPtr->typePtr to the argument value typePtr,  but  that	is  no	longer
       guaranteed.  The setFromAnyProc is free to set the internal representa‐
       tion for objPtr to make use of another related Tcl_ObjType, if it  sees
       fit.

THE TCL_OBJTYPE STRUCTURE
       Extension  writers  can	define new value types by defining four proce‐
       dures and initializing a Tcl_ObjType structure to  describe  the	 type.
       Extension  writers  may also pass a pointer to their Tcl_ObjType struc‐
       ture to Tcl_RegisterObjType if they wish to permit other extensions  to
       look up their Tcl_ObjType by name with the Tcl_GetObjType routine.  The
       Tcl_ObjType structure is defined as follows:

	      typedef struct Tcl_ObjType {
		  const char *name;
		  Tcl_FreeInternalRepProc *freeIntRepProc;
		  Tcl_DupInternalRepProc *dupIntRepProc;
		  Tcl_UpdateStringProc *updateStringProc;
		  Tcl_SetFromAnyProc *setFromAnyProc;
	      } Tcl_ObjType;

   THE NAME FIELD
       The name member describes the name of the type, e.g. int.  When a  type
       is  registered,	this  is the name used by callers of Tcl_GetObjType to
       lookup the type.	 For unregistered types, the name field	 is  primarily
       of  value  for  debugging.   The remaining four members are pointers to
       procedures called by the generic Tcl value code:

   THE SETFROMANYPROC FIELD
       The setFromAnyProc member contains the address of a function called  to
       create  a valid internal representation from a value's string represen‐
       tation.

	      typedef int Tcl_SetFromAnyProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *objPtr);

       If an internal representation cannot be created from the string, it re‐
       turns  TCL_ERROR	 and puts a message describing the error in the result
       value for interp unless interp is NULL.	If setFromAnyProc is  success‐
       ful,  it	 stores the new internal representation, sets objPtr's typePtr
       member to point to the Tcl_ObjType struct corresponding to the new  in‐
       ternal  representation, and returns TCL_OK.  Before setting the new in‐
       ternal representation, the setFromAnyProc must free any internal repre‐
       sentation  of objPtr's old type; it does this by calling the old type's
       freeIntRepProc if it is not NULL.

       As an example, the setFromAnyProc for the built-in Tcl list  type  gets
       an  up-to-date  string  representation  for  objPtr by calling Tcl_Get‐
       StringFromObj.  It parses the string to verify it is in	a  valid  list
       format  and to obtain each element value in the list, and, if this suc‐
       ceeds, stores the list elements in objPtr's internal representation and
       sets  objPtr's  typePtr	member to point to the list type's Tcl_ObjType
       structure.

       Do not release objPtr's old internal representation unless you  replace
       it with a new one or reset the typePtr member to NULL.

       The  setFromAnyProc  member  may be set to NULL, if the routines making
       use of the internal representation have no need to derive that internal
       representation  from an arbitrary string value.	However, in this case,
       passing a pointer to the type  to  Tcl_ConvertToType  will  lead	 to  a
       panic, so to avoid this possibility, the type should not be registered.

   THE UPDATESTRINGPROC FIELD
       The  updateStringProc  member contains the address of a function called
       to create a valid string representation from a value's internal	repre‐
       sentation.

	      typedef void Tcl_UpdateStringProc(
		      Tcl_Obj *objPtr);

       objPtr's bytes member is always NULL when it is called.	It must always
       set bytes non-NULL before returning.  We require the string representa‐
       tion's byte array to have a null after the last byte, at offset length,
       and to have no null bytes before that; this allows  string  representa‐
       tions  to  be  treated  as  conventional	 null  character-terminated  C
       strings.	 These restrictions are easily met by using Tcl's internal UTF
       encoding	 for the string representation, same as one would do for other
       Tcl routines accepting string values as	arguments.   Storage  for  the
       byte array must be allocated in the heap by Tcl_Alloc or ckalloc.  Note
       that updateStringProcs must allocate enough storage  for	 the  string's
       bytes and the terminating null byte.

       The updateStringProc for Tcl's built-in double type, for example, calls
       Tcl_PrintDouble to write to a buffer of size TCL_DOUBLE_SPACE, then al‐
       locates	and  copies  the string representation to just enough space to
       hold it.	 A pointer to the allocated space is stored in the bytes  mem‐
       ber.

       The  updateStringProc member may be set to NULL, if the routines making
       use of the internal representation are written so that the string  rep‐
       resentation is never invalidated.  Failure to meet this obligation will
       lead to panics or crashes when Tcl_GetStringFromObj  or	other  similar
       routines ask for the string representation.

   THE DUPINTREPPROC FIELD
       The  dupIntRepProc  member contains the address of a function called to
       copy an internal representation from one value to another.

	      typedef void Tcl_DupInternalRepProc(
		      Tcl_Obj *srcPtr,
		      Tcl_Obj *dupPtr);

       dupPtr's internal representation is made a copy	of  srcPtr's  internal
       representation.	 Before	 the call, srcPtr's internal representation is
       valid and dupPtr's is not.  srcPtr's value type determines what copying
       its internal representation means.

       For  example,  the dupIntRepProc for the Tcl integer type simply copies
       an integer.  The built-in list type's dupIntRepProc uses a far more so‐
       phisticated scheme to continue sharing storage as much as it reasonably
       can.

   THE FREEINTREPPROC FIELD
       The freeIntRepProc member contains the address of a  function  that  is
       called when a value is freed.

	      typedef void Tcl_FreeInternalRepProc(
		      Tcl_Obj *objPtr);

       The  freeIntRepProc function can deallocate the storage for the value's
       internal representation and do other type-specific processing necessary
       when a value is freed.

       For  example, the list type's freeIntRepProc respects the storage shar‐
       ing scheme established by the dupIntRepProc so that it only frees stor‐
       age when the last value sharing it is being freed.

       The  freeIntRepProc  member can be set to NULL to indicate that the in‐
       ternal representation does not require freeing.	The freeIntRepProc im‐
       plementation  must  not access the bytes member of the value, since Tcl
       makes its own internal uses of that field during value  deletion.   The
       defined	tasks for the freeIntRepProc have no need to consult the bytes
       member.

SEE ALSO
       Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3)

KEYWORDS
       internal representation, value, value type, string representation, type
       conversion



Tcl				      8.0			Tcl_ObjType(3)

Tcl_SetErrno(3)		    Tcl Library Procedures	       Tcl_SetErrno(3)



______________________________________________________________________________

NAME
       Tcl_SetErrno,  Tcl_GetErrno, Tcl_ErrnoId, Tcl_ErrnoMsg - manipulate er‐
       rno to store and retrieve error codes

SYNOPSIS
       #include <tcl.h>

       void
       Tcl_SetErrno(errorCode)

       int
       Tcl_GetErrno()

       const char *
       Tcl_ErrnoId()

       const char *
       Tcl_ErrnoMsg(errorCode)


ARGUMENTS
       int errorCode (in)	   A POSIX error code such as ENOENT.
______________________________________________________________________________


DESCRIPTION
       Tcl_SetErrno and Tcl_GetErrno provide  portable	access	to  the	 errno
       variable, which is used to record a POSIX error code after system calls
       and other operations such as Tcl_Gets.  These procedures are  necessary
       because	global	variable  accesses cannot be made across module bound‐
       aries on some platforms.

       Tcl_SetErrno sets the errno variable to the value of the errorCode  ar‐
       gument  C  procedures  that  wish  to return error information to their
       callers via errno should call Tcl_SetErrno rather  than	setting	 errno
       directly.

       Tcl_GetErrno returns the current value of errno.	 Procedures wishing to
       access errno should call this procedure instead of accessing errno  di‐
       rectly.

       Tcl_ErrnoId  and	 Tcl_ErrnoMsg  return  string representations of errno
       values.	Tcl_ErrnoId returns a machine-readable textual identifier such
       as  “EACCES”  that  corresponds to the current value of errno.  Tcl_Er‐
       rnoMsg returns a human-readable string such as “permission denied” that
       corresponds  to the value of its errorCode argument.  The errorCode ar‐
       gument is typically the value returned by  Tcl_GetErrno.	  The  strings
       returned	 by  these  functions  are statically allocated and the caller
       must not free or modify them.


KEYWORDS
       errno, error code, global variables



Tcl				      8.3		       Tcl_SetErrno(3)

Tcl_CreateChannel(3)	    Tcl Library Procedures	  Tcl_CreateChannel(3)



______________________________________________________________________________

NAME
       Tcl_CreateChannel,    Tcl_GetChannelInstanceData,   Tcl_GetChannelType,
       Tcl_GetChannelName,	Tcl_GetChannelHandle,	   Tcl_GetChannelMode,
       Tcl_GetChannelBufferSize,  Tcl_SetChannelBufferSize, Tcl_NotifyChannel,
       Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_Channel‐
       BlockModeProc,  Tcl_ChannelCloseProc,  Tcl_ChannelClose2Proc, Tcl_Chan‐
       nelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc,  Tcl_Channel‐
       WideSeekProc,	 Tcl_ChannelTruncateProc,    Tcl_ChannelSetOptionProc,
       Tcl_ChannelGetOptionProc,    Tcl_ChannelWatchProc,     Tcl_ChannelGetH‐
       andleProc,   Tcl_ChannelFlushProc,   Tcl_ChannelHandlerProc,  Tcl_Chan‐
       nelThreadActionProc,   Tcl_IsChannelShared,    Tcl_IsChannelRegistered,
       Tcl_CutChannel,	      Tcl_SpliceChannel,	Tcl_IsChannelExisting,
       Tcl_ClearChannelHandlers, Tcl_GetChannelThread,	Tcl_ChannelBuffered  -
       procedures for creating and manipulating channels

SYNOPSIS
       #include <tcl.h>

       Tcl_Channel
       Tcl_CreateChannel(typePtr, channelName, instanceData, mask)

       ClientData
       Tcl_GetChannelInstanceData(channel)

       const Tcl_ChannelType *
       Tcl_GetChannelType(channel)

       const char *
       Tcl_GetChannelName(channel)

       int
       Tcl_GetChannelHandle(channel, direction, handlePtr)

       Tcl_ThreadId
       Tcl_GetChannelThread(channel)

       int
       Tcl_GetChannelMode(channel)

       int
       Tcl_GetChannelBufferSize(channel)

       Tcl_SetChannelBufferSize(channel, size)

       Tcl_NotifyChannel(channel, mask)

       int
       Tcl_BadChannelOption(interp, optionName, optionList)

       int
       Tcl_IsChannelShared(channel)

       int
       Tcl_IsChannelRegistered(interp, channel)

       int
       Tcl_IsChannelExisting(channelName)

       void
       Tcl_CutChannel(channel)

       void
       Tcl_SpliceChannel(channel)

       void
       Tcl_ClearChannelHandlers(channel)

       int
       Tcl_ChannelBuffered(channel)

       const char *
       Tcl_ChannelName(typePtr)

       Tcl_ChannelTypeVersion
       Tcl_ChannelVersion(typePtr)

       Tcl_DriverBlockModeProc *
       Tcl_ChannelBlockModeProc(typePtr)

       Tcl_DriverCloseProc *
       Tcl_ChannelCloseProc(typePtr)

       Tcl_DriverClose2Proc *
       Tcl_ChannelClose2Proc(typePtr)

       Tcl_DriverInputProc *
       Tcl_ChannelInputProc(typePtr)

       Tcl_DriverOutputProc *
       Tcl_ChannelOutputProc(typePtr)

       Tcl_DriverSeekProc *
       Tcl_ChannelSeekProc(typePtr)

       Tcl_DriverWideSeekProc *
       Tcl_ChannelWideSeekProc(typePtr)

       Tcl_DriverThreadActionProc *
       Tcl_ChannelThreadActionProc(typePtr)

       Tcl_DriverTruncateProc *
       Tcl_ChannelTruncateProc(typePtr)

       Tcl_DriverSetOptionProc *
       Tcl_ChannelSetOptionProc(typePtr)

       Tcl_DriverGetOptionProc *
       Tcl_ChannelGetOptionProc(typePtr)

       Tcl_DriverWatchProc *
       Tcl_ChannelWatchProc(typePtr)

       Tcl_DriverGetHandleProc *
       Tcl_ChannelGetHandleProc(typePtr)

       Tcl_DriverFlushProc *
       Tcl_ChannelFlushProc(typePtr)

       Tcl_DriverHandlerProc *
       Tcl_ChannelHandlerProc(typePtr)


ARGUMENTS
       const Tcl_ChannelType *typePtr (in)		Points	to a structure
							containing   the   ad‐
							dresses	 of procedures
							that can be called  to
							perform	 I/O and other
							functions on the chan‐
							nel.

       const char *channelName (in)			The name of this chan‐
							nel,  such  as	file3;
							must  not be in use by
							any other channel. Can
							be NULL, in which case
							the channel is created
							without a name. If the
							created channel is as‐
							signed	to  one of the
							standard      channels
							(stdin,	   stdout   or
							stderr), the  assigned
							channel	 name  will be
							the name of the	 stan‐
							dard channel.

       ClientData instanceData (in)			Arbitrary     one-word
							value to be associated
							with   this   channel.
							This value  is	passed
							to procedures in type‐
							Ptr when they are  in‐
							voked.

       int mask (in)					OR-ed  combination  of
							TCL_READABLE	   and
							TCL_WRITABLE  to indi‐
							cate whether a channel
							is     readable	   and
							writable.

       Tcl_Channel channel (in)				The channel to operate
							on.

       int direction (in)				TCL_READABLE means the
							input	 handle	    is
							wanted;	  TCL_WRITABLE
							means the output  han‐
							dle is wanted.

       ClientData *handlePtr (out)			Points to the location
							where the desired  OS-
							specific handle should
							be stored.

       int size (in)					The size, in bytes, of
							buffers to allocate in
							this channel.

       int mask (in)					An  OR-ed  combination
							of	 TCL_READABLE,
							TCL_WRITABLE	   and
							TCL_EXCEPTION that in‐
							dicates	 events	  that
							have  occurred on this
							channel.

       Tcl_Interp *interp (in)				Current	  interpreter.
							(can be NULL)

       const char *optionName (in)			Name  of  the  invalid
							option.

       const char *optionList (in)			Specific options  list
							(space	     separated
							words, without “-”) to
							append to the standard
							generic options	 list.
							Can    be   NULL   for
							generic options	 error
							message only.
______________________________________________________________________________

DESCRIPTION
       Tcl  uses a two-layered channel architecture. It provides a generic up‐
       per layer to enable C and Tcl programs to perform input and output  us‐
       ing  the	 same  APIs  for a variety of files, devices, sockets etc. The
       generic C APIs are described in the manual entry for  Tcl_OpenFileChan‐
       nel.

       The lower layer provides type-specific channel drivers for each type of
       device supported on each platform.  This manual entry describes	the  C
       APIs  used  to  communicate between the generic layer and the type-spe‐
       cific channel drivers.  It also explains how new types of channels  can
       be added by providing new channel drivers.

       Channel	drivers consist of a number of components: First, each channel
       driver provides a  Tcl_ChannelType  structure  containing  pointers  to
       functions implementing the various operations used by the generic layer
       to communicate with the channel driver. The  Tcl_ChannelType  structure
       and  the	 functions  referenced	by  it	are  described	in the section
       TCL_CHANNELTYPE, below.

       Second, channel drivers usually provide a Tcl  command  to  create  in‐
       stances of that type of channel. For example, the Tcl open command cre‐
       ates channels that use the file and command channel  drivers,  and  the
       Tcl  socket  command  creates channels that use TCP sockets for network
       communication.

       Third, a channel driver optionally provides a C function to open	 chan‐
       nel  instances  of  that type. For example, Tcl_OpenFileChannel opens a
       channel that uses the file channel driver, and Tcl_OpenTcpClient	 opens
       a channel that uses the TCP network protocol.  These creation functions
       typically use Tcl_CreateChannel internally to open the channel.

       To add a new type of channel you must implement a C API or a  Tcl  com‐
       mand  that  opens  a  channel by invoking Tcl_CreateChannel.  When your
       driver calls Tcl_CreateChannel it passes in a Tcl_ChannelType structure
       describing  the	driver's  I/O procedures.  The generic layer will then
       invoke the functions referenced in that structure to perform operations
       on the channel.

       Tcl_CreateChannel opens a new channel and associates the supplied type‐
       Ptr and instanceData with it. The channel is opened in the  mode	 indi‐
       cated  by  mask.	 For a discussion of channel drivers, their operations
       and the Tcl_ChannelType structure, see the section TCL_CHANNELTYPE, be‐
       low.

       Tcl_CreateChannel  interacts  with the code managing the standard chan‐
       nels. Once a standard channel was initialized either through a call  to
       Tcl_GetStdChannel  or a call to Tcl_SetStdChannel closing this standard
       channel will cause the next call to Tcl_CreateChannel to make  the  new
       channel	the  new  standard channel too. See Tcl_StandardChannels for a
       general treatise about standard channels and the behavior  of  the  Tcl
       library with regard to them.

       Tcl_GetChannelInstanceData  returns  the	 instance data associated with
       the channel in channel. This is the same as the	instanceData  argument
       in the call to Tcl_CreateChannel that created this channel.

       Tcl_GetChannelType  returns  a pointer to the Tcl_ChannelType structure
       used by the channel in the channel argument. This is the	 same  as  the
       typePtr	argument  in  the  call to Tcl_CreateChannel that created this
       channel.

       Tcl_GetChannelName returns a string containing the name associated with
       the  channel,  or NULL if the channelName argument to Tcl_CreateChannel
       was NULL.

       Tcl_GetChannelHandle places the OS-specific  device  handle  associated
       with  channel for the given direction in the location specified by han‐
       dlePtr and returns TCL_OK.  If the channel does not have a device  han‐
       dle  for	 the  specified direction, then TCL_ERROR is returned instead.
       Different channel drivers will return different types of handle.	 Refer
       to  the manual entries for each driver to determine what type of handle
       is returned.

       Tcl_GetChannelThread returns the id of the  thread  currently  managing
       the  specified  channel. This allows channel drivers to send their file
       events to the correct event queue even for a multi-threaded core.

       Tcl_GetChannelMode returns an OR-ed  combination	 of  TCL_READABLE  and
       TCL_WRITABLE, indicating whether the channel is open for input and out‐
       put.

       Tcl_GetChannelBufferSize returns the size, in bytes, of	buffers	 allo‐
       cated  to store input or output in channel. If the value was not set by
       a previous call to Tcl_SetChannelBufferSize, described below, then  the
       default value of 4096 is returned.

       Tcl_SetChannelBufferSize	 sets the size, in bytes, of buffers that will
       be allocated in subsequent operations on the channel to store input  or
       output. The size argument should be between one and one million, allow‐
       ing buffers of one byte to one million bytes. If size is	 outside  this
       range, Tcl_SetChannelBufferSize sets the buffer size to 4096.

       Tcl_NotifyChannel  is  called  by  a  channel driver to indicate to the
       generic layer that the events specified by mask have  occurred  on  the
       channel.	  Channel  drivers  are responsible for invoking this function
       whenever the channel handlers need to be called	for  the  channel  (or
       other  pending  tasks  like  a  write  flush should be performed).  See
       WATCHPROC below for more details.

       Tcl_BadChannelOption is called from driver  specific  setOptionProc  or
       getOptionProc to generate a complete error message.

       Tcl_ChannelBuffered  returns  the  number  of  bytes of input currently
       buffered in the internal buffer (push back area) of the channel itself.
       It  does not report about the data in the overall buffers for the stack
       of channels the supplied channel is part of.

       Tcl_IsChannelShared checks the refcount of the  specified  channel  and
       returns whether the channel was shared among multiple interpreters (re‐
       sult == 1) or not (result == 0).

       Tcl_IsChannelRegistered checks whether the specified channel is	regis‐
       tered in the given interpreter (result == 1) or not (result == 0).

       Tcl_IsChannelExisting  checks whether a channel with the specified name
       is registered in the (thread)-global list of all channels (result == 1)
       or not (result == 0).

       Tcl_CutChannel  removes	the  specified channel from the (thread)global
       list of all channels (of the current thread).  Application to a channel
       still registered in some interpreter is not allowed.  Also notifies the
       driver if the  Tcl_ChannelType  version	is  TCL_CHANNEL_VERSION_4  (or
       higher), and Tcl_DriverThreadActionProc is defined for it.

       Tcl_SpliceChannel adds the specified channel to the (thread)global list
       of all channels (of the current thread).	 Application to a channel reg‐
       istered	in  some interpreter is not allowed.  Also notifies the driver
       if the Tcl_ChannelType version is  TCL_CHANNEL_VERSION_4	 (or  higher),
       and Tcl_DriverThreadActionProc is defined for it.

       Tcl_ClearChannelHandlers removes all channel handlers and event scripts
       associated with the specified channel, thus  shutting  down  all	 event
       processing for this channel.

TCL_CHANNELTYPE
       A  channel  driver  provides  a Tcl_ChannelType structure that contains
       pointers to functions that implement the various operations on a	 chan‐
       nel;  these operations are invoked as needed by the generic layer.  The
       structure was versioned starting in Tcl 8.3.2/8.4 to correct a  problem
       with  stacked channel drivers.  See the OLD CHANNEL TYPES section below
       for details about the old structure.

       The Tcl_ChannelType structure contains the following fields:

	      typedef struct Tcl_ChannelType {
		      const char *typeName;
		      Tcl_ChannelTypeVersion version;
		      Tcl_DriverCloseProc *closeProc;
		      Tcl_DriverInputProc *inputProc;
		      Tcl_DriverOutputProc *outputProc;
		      Tcl_DriverSeekProc *seekProc;
		      Tcl_DriverSetOptionProc *setOptionProc;
		      Tcl_DriverGetOptionProc *getOptionProc;
		      Tcl_DriverWatchProc *watchProc;
		      Tcl_DriverGetHandleProc *getHandleProc;
		      Tcl_DriverClose2Proc *close2Proc;
		      Tcl_DriverBlockModeProc *blockModeProc;
		      Tcl_DriverFlushProc *flushProc;
		      Tcl_DriverHandlerProc *handlerProc;
		      Tcl_DriverWideSeekProc *wideSeekProc;
		      Tcl_DriverThreadActionProc *threadActionProc;
		      Tcl_DriverTruncateProc *truncateProc;
	      } Tcl_ChannelType;

       It is not necessary to provide implementations for all  channel	opera‐
       tions.  Those which are not necessary may be set to NULL in the struct:
       blockModeProc, seekProc, setOptionProc,	getOptionProc,	getHandleProc,
       and  close2Proc,	 in  addition to flushProc, handlerProc, threadAction‐
       Proc, and truncateProc.	Other functions that cannot be implemented  in
       a meaningful way should return EINVAL when called, to indicate that the
       operations  they	 represent  are	 not   available.   Also   note	  that
       wideSeekProc can be NULL if seekProc is.

       The  user  should  only use the above structure for Tcl_ChannelType in‐
       stantiation.  When referencing fields in a  Tcl_ChannelType  structure,
       the  following functions should be used to obtain the values: Tcl_Chan‐
       nelName,	 Tcl_ChannelVersion,  Tcl_ChannelBlockModeProc,	  Tcl_Channel‐
       CloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOut‐
       putProc,	  Tcl_ChannelSeekProc,	 Tcl_ChannelWideSeekProc,    Tcl_Chan‐
       nelThreadActionProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc,
       Tcl_ChannelGetOptionProc,    Tcl_ChannelWatchProc,     Tcl_ChannelGetH‐
       andleProc, Tcl_ChannelFlushProc, or Tcl_ChannelHandlerProc.

       The change to the structures was made in such a way that standard chan‐
       nel types are binary  compatible.   However,  channel  types  that  use
       stacked channels (i.e. TLS, Trf) have new versions to correspond to the
       above change since the previous code for stacked channels had problems.

   TYPENAME
       The typeName field contains a null-terminated  string  that  identifies
       the  type  of  the  device  implemented	by  this driver, e.g.  file or
       socket.

       This value can be  retrieved  with  Tcl_ChannelName,  which  returns  a
       pointer to the string.

   VERSION
       The  version  field  should be set to the version of the structure that
       you  require.  TCL_CHANNEL_VERSION_2  is	  the	minimum	  recommended.
       TCL_CHANNEL_VERSION_3  must  be set to specify the wideSeekProc member.
       TCL_CHANNEL_VERSION_4 must be set to specify the threadActionProc  mem‐
       ber  (includes  wideSeekProc).	TCL_CHANNEL_VERSION_5  must  be set to
       specify the truncateProc members (includes wideSeekProc	and  threadAc‐
       tionProc).  If it is not set to any of these, then this Tcl_ChannelType
       is assumed to have the original structure.  See OLD CHANNEL  TYPES  for
       more details.  While Tcl will recognize and function with either struc‐
       tures, stacked channels must be of at  least  TCL_CHANNEL_VERSION_2  to
       function correctly.

       This  value can be retrieved with Tcl_ChannelVersion, which returns one
       of TCL_CHANNEL_VERSION_5, TCL_CHANNEL_VERSION_4, TCL_CHANNEL_VERSION_3,
       TCL_CHANNEL_VERSION_2 or TCL_CHANNEL_VERSION_1.

   BLOCKMODEPROC
       The  blockModeProc  field  contains the address of a function called by
       the generic layer to set blocking and nonblocking mode on  the  device.
       BlockModeProc should match the following prototype:

	      typedef int Tcl_DriverBlockModeProc(
		      ClientData instanceData,
		      int mode);

       The  instanceData  is the same as the value passed to Tcl_CreateChannel
       when  this  channel  was	 created.   The	 mode	argument   is	either
       TCL_MODE_BLOCKING or TCL_MODE_NONBLOCKING to set the device into block‐
       ing or nonblocking mode. The function should return zero if the	opera‐
       tion  was  successful,  or  a nonzero POSIX error code if the operation
       failed.

       If the operation is successful, the function can	 modify	 the  supplied
       instanceData to record that the channel entered blocking or nonblocking
       mode and to implement the blocking or nonblocking behavior.   For  some
       device  types, the blocking and nonblocking behavior can be implemented
       by the underlying operating system; for other device types, the	behav‐
       ior must be emulated in the channel driver.

       This  value  can	 be retrieved with Tcl_ChannelBlockModeProc, which re‐
       turns a pointer to the function.

       A channel driver not supplying a blockModeProc has  to  be  very,  very
       careful.	 It  has to tell the generic layer exactly which blocking mode
       is acceptable to it, and should this also document for the user so that
       the  blocking  mode  of	the  channel is not changed to an unacceptable
       value. Any confusion here may lead the interpreter into a (spurious and
       difficult to find) deadlock.

   CLOSEPROC AND CLOSE2PROC
       The  closeProc  field  contains the address of a function called by the
       generic layer to clean up driver-related information when  the  channel
       is closed. CloseProc must match the following prototype:

	      typedef int Tcl_DriverCloseProc(
		      ClientData instanceData,
		      Tcl_Interp *interp);

       The instanceData argument is the same as the value provided to Tcl_Cre‐
       ateChannel when the channel was created. The  function  should  release
       any  storage  maintained	 by  the  channel driver for this channel, and
       close the input and output devices encapsulated by  this	 channel.  All
       queued output will have been flushed to the device before this function
       is called, and no further driver operations will be invoked on this in‐
       stance  after calling the closeProc. If the close operation is success‐
       ful, the procedure should return zero; otherwise	 it  should  return  a
       nonzero POSIX error code. In addition, if an error occurs and interp is
       not NULL, the procedure should store an error  message  in  the	inter‐
       preter's result.

       Alternatively,  channels	 that support closing the read and write sides
       independently may set closeProc to TCL_CLOSE2PROC and set close2Proc to
       the address of a function that matches the following prototype:

	      typedef int Tcl_DriverClose2Proc(
		      ClientData instanceData,
		      Tcl_Interp *interp,
		      int flags);

       The close2Proc will be called with flags set to an OR'ed combination of
       TCL_CLOSE_READ or TCL_CLOSE_WRITE to indicate that  the	driver	should
       close  the  read	 and/or write side of the channel.  The channel driver
       may be invoked to perform additional operations on  the	channel	 after
       close2Proc  is  called  to  close one or both sides of the channel.  If
       flags is 0 (zero), the driver should close the channel  in  the	manner
       described  above	 for closeProc.	 No further operations will be invoked
       on this instance after close2Proc is called with all flags cleared.  In
       all  cases, the close2Proc function should return zero if the close op‐
       eration was successful; otherwise it should return a nonzero POSIX  er‐
       ror  code.  In addition, if an error occurs and interp is not NULL, the
       procedure should store an error message in the interpreter's result.

       The closeProc and close2Proc values can be retrieved with  Tcl_Channel‐
       CloseProc  or  Tcl_ChannelClose2Proc, which return a pointer to the re‐
       spective function.

   INPUTPROC
       The inputProc field contains the address of a function  called  by  the
       generic	layer  to read data from the file or device and store it in an
       internal buffer. InputProc must match the following prototype:

	      typedef int Tcl_DriverInputProc(
		      ClientData instanceData,
		      char *buf,
		      int bufSize,
		      int *errorCodePtr);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       the  channel was created.  The buf argument points to an array of bytes
       in which to store input from the device, and the bufSize argument indi‐
       cates how many bytes are available at buf.

       The errorCodePtr argument points to an integer variable provided by the
       generic layer. If an error occurs, the function should set the variable
       to a POSIX error code that identifies the error that occurred.

       The function should read data from the input device encapsulated by the
       channel and store it at buf.  On success, the function should return  a
       nonnegative  integer indicating how many bytes were read from the input
       device and stored at buf. On error, the function should return  -1.  If
       an  error  occurs  after	 some data has been read from the device, that
       data is lost.

       If inputProc can determine that the input device has some  data	avail‐
       able  but  less	than  requested	 by the bufSize argument, the function
       should only attempt to read as much data as  is	available  and	return
       without	blocking. If the input device has no data available whatsoever
       and the channel is in nonblocking mode, the function should  return  an
       EAGAIN  error. If the input device has no data available whatsoever and
       the channel is in blocking mode, the  function  should  block  for  the
       shortest possible time until at least one byte of data can be read from
       the device; then, it should return as much data as it can read  without
       blocking.

       This  value can be retrieved with Tcl_ChannelInputProc, which returns a
       pointer to the function.

   OUTPUTPROC
       The outputProc field contains the address of a function called  by  the
       generic	layer  to  transfer data from an internal buffer to the output
       device.	OutputProc must match the following prototype:

	      typedef int Tcl_DriverOutputProc(
		      ClientData instanceData,
		      const char *buf,
		      int toWrite,
		      int *errorCodePtr);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       the channel was created. The buf argument contains an array of bytes to
       be written to the device, and the toWrite argument indicates  how  many
       bytes are to be written from the buf argument.

       The errorCodePtr argument points to an integer variable provided by the
       generic layer. If an error occurs, the function should set  this	 vari‐
       able to a POSIX error code that identifies the error.

       The function should write the data at buf to the output device encapsu‐
       lated by the channel. On success, the function should return a nonnega‐
       tive  integer  indicating how many bytes were written to the output de‐
       vice.  The return value is normally the same as	toWrite,  but  may  be
       less  in some cases such as if the output operation is interrupted by a
       signal. If an error occurs the function should return -1.  In  case  of
       error, some data may have been written to the device.

       If the channel is nonblocking and the output device is unable to absorb
       any data whatsoever, the function should return -1 with an EAGAIN error
       without writing any data.

       This value can be retrieved with Tcl_ChannelOutputProc, which returns a
       pointer to the function.

   SEEKPROC AND WIDESEEKPROC
       The seekProc field contains the address of a  function  called  by  the
       generic	layer  to  move	 the access point at which subsequent input or
       output operations will be applied. SeekProc must	 match	the  following
       prototype:

	      typedef int Tcl_DriverSeekProc(
		      ClientData instanceData,
		      long offset,
		      int seekMode,
		      int *errorCodePtr);

       The instanceData argument is the same as the value given to Tcl_Create‐
       Channel when this channel was created.  Offset and  seekMode  have  the
       same meaning as for the Tcl_Seek procedure (described in the manual en‐
       try for Tcl_OpenFileChannel).

       The errorCodePtr argument points to an integer variable provided by the
       generic	layer for returning errno values from the function.  The func‐
       tion should set this variable to a POSIX error code if an error occurs.
       The function should store an EINVAL error code if the channel type does
       not implement seeking.

       The return value is the new access point or -1 in case of error. If  an
       error occurred, the function should not move the access point.

       If  there is a non-NULL seekProc field, the wideSeekProc field may con‐
       tain the address of an alternative function to use which	 handles  wide
       (i.e.  larger  than  32-bit)  offsets,  so  allowing seeks within files
       larger than 2GB.	 The wideSeekProc will be called in preference to  the
       seekProc,  but  both  must  be  defined if the wideSeekProc is defined.
       WideSeekProc must match the following prototype:

	      typedef Tcl_WideInt Tcl_DriverWideSeekProc(
		      ClientData instanceData,
		      Tcl_WideInt offset,
		      int seekMode,
		      int *errorCodePtr);

       The arguments and return values mean the same thing  as	with  seekProc
       above,  except that the type of offsets and the return type are differ‐
       ent.

       The seekProc value can be retrieved with Tcl_ChannelSeekProc, which re‐
       turns  a pointer to the function, and similarly the wideSeekProc can be
       retrieved with Tcl_ChannelWideSeekProc.

   SETOPTIONPROC
       The setOptionProc field contains the address of a  function  called  by
       the  generic  layer to set a channel type specific option on a channel.
       setOptionProc must match the following prototype:

	      typedef int Tcl_DriverSetOptionProc(
		      ClientData instanceData,
		      Tcl_Interp *interp,
		      const char *optionName,
		      const char *newValue);

       optionName is the name of an option to set, and	newValue  is  the  new
       value for that option, as a string. The instanceData is the same as the
       value given to Tcl_CreateChannel when this  channel  was	 created.  The
       function should do whatever channel type specific action is required to
       implement the new value of the option.

       Some options are handled by the generic code and this function is never
       called to set them, e.g. -blockmode. Other options are specific to each
       channel type and the setOptionProc procedure of the channel driver will
       get  called  to	implement  them.  The setOptionProc field can be NULL,
       which indicates that this channel type supports no  type	 specific  op‐
       tions.

       If  the	option	value  is  successfully modified to the new value, the
       function returns TCL_OK.	 It should call Tcl_BadChannelOption which it‐
       self  returns TCL_ERROR if the optionName is unrecognized.  If newValue
       specifies a value for the option that is not supported or if  a	system
       call  error  occurs,  the function should leave an error message in the
       result of interp if interp is not NULL. The function should  also  call
       Tcl_SetErrno to store an appropriate POSIX error code.

       This  value  can	 be retrieved with Tcl_ChannelSetOptionProc, which re‐
       turns a pointer to the function.

   GETOPTIONPROC
       The getOptionProc field contains the address of a  function  called  by
       the generic layer to get the value of a channel type specific option on
       a channel. getOptionProc must match the following prototype:

	      typedef int Tcl_DriverGetOptionProc(
		      ClientData instanceData,
		      Tcl_Interp *interp,
		      const char *optionName,
		      Tcl_DString *optionValue);

       OptionName is the name of an option supported by this type of  channel.
       If  the option name is not NULL, the function stores its current value,
       as a string, in the Tcl dynamic string optionValue.  If	optionName  is
       NULL,  the  function  stores  in optionValue an alternating list of all
       supported options and their current values.  On success,	 the  function
       returns	TCL_OK.	  It should call Tcl_BadChannelOption which itself re‐
       turns TCL_ERROR if the optionName is unrecognized. If a system call er‐
       ror occurs, the function should leave an error message in the result of
       interp if interp is not NULL. The function should also call  Tcl_SetEr‐
       rno to store an appropriate POSIX error code.

       Some options are handled by the generic code and this function is never
       called to retrieve their value, e.g. -blockmode. Other options are spe‐
       cific to each channel type and the getOptionProc procedure of the chan‐
       nel driver will get called to implement them. The  getOptionProc	 field
       can  be	NULL,  which indicates that this channel type supports no type
       specific options.

       This value can be retrieved with	 Tcl_ChannelGetOptionProc,  which  re‐
       turns a pointer to the function.

   WATCHPROC
       The  watchProc  field  contains the address of a function called by the
       generic layer to initialize the event notification mechanism to	notice
       events of interest on this channel.  WatchProc should match the follow‐
       ing prototype:

	      typedef void Tcl_DriverWatchProc(
		      ClientData instanceData,
		      int mask);

       The instanceData is the same as the value passed	 to  Tcl_CreateChannel
       when  this  channel was created. The mask argument is an OR-ed combina‐
       tion of TCL_READABLE,  TCL_WRITABLE  and	 TCL_EXCEPTION;	 it  indicates
       events the caller is interested in noticing on this channel.

       The  function  should initialize device type specific mechanisms to no‐
       tice when an event of interest is present on the channel.  When one  or
       more of the designated events occurs on the channel, the channel driver
       is responsible for calling  Tcl_NotifyChannel  to  inform  the  generic
       channel	module.	 The driver should take care not to starve other chan‐
       nel drivers or sources of callbacks by invoking	Tcl_NotifyChannel  too
       frequently.   Fairness  can  be insured by using the Tcl event queue to
       allow the channel event to be scheduled in sequence with other  events.
       See  the	 description  of Tcl_QueueEvent for details on how to queue an
       event.

       This value can be retrieved with Tcl_ChannelWatchProc, which returns  a
       pointer to the function.

   GETHANDLEPROC
       The  getHandleProc  field  contains the address of a function called by
       the generic layer to retrieve a device-specific handle from  the	 chan‐
       nel.  GetHandleProc should match the following prototype:

	      typedef int Tcl_DriverGetHandleProc(
		      ClientData instanceData,
		      int direction,
		      ClientData *handlePtr);

       InstanceData  is the same as the value passed to Tcl_CreateChannel when
       this channel was created. The direction argument is either TCL_READABLE
       to  retrieve the handle used for input, or TCL_WRITABLE to retrieve the
       handle used for output.

       If the channel implementation has device-specific handles, the function
       should retrieve the appropriate handle associated with the channel, ac‐
       cording the direction argument.	The handle should be stored in the lo‐
       cation referred to by handlePtr, and TCL_OK should be returned.	If the
       channel is not open for the specified direction, or if the channel  im‐
       plementation  does  not	use device handles, the function should return
       TCL_ERROR.

       This value can be retrieved with	 Tcl_ChannelGetHandleProc,  which  re‐
       turns a pointer to the function.

   FLUSHPROC
       The flushProc field is currently reserved for future use.  It should be
       set to NULL.  FlushProc should match the following prototype:

	      typedef int Tcl_DriverFlushProc(
		      ClientData instanceData);

       This value can be retrieved with Tcl_ChannelFlushProc, which returns  a
       pointer to the function.

   HANDLERPROC
       The  handlerProc field contains the address of a function called by the
       generic layer to notify the channel that an event occurred.  It	should
       be  defined  for	 stacked  channel  drivers that wish to be notified of
       events that occur on the	 underlying  (stacked)	channel.   HandlerProc
       should match the following prototype:

	      typedef int Tcl_DriverHandlerProc(
		      ClientData instanceData,
		      int interestMask);

       InstanceData  is the same as the value passed to Tcl_CreateChannel when
       this channel was created.  The interestMask is an OR-ed combination  of
       TCL_READABLE  or TCL_WRITABLE; it indicates what type of event occurred
       on this channel.

       This value can be retrieved with Tcl_ChannelHandlerProc, which  returns
       a pointer to the function.


   THREADACTIONPROC
       The  threadActionProc field contains the address of the function called
       by the generic layer when a channel is created,	closed,	 or  going  to
       move  to a different thread, i.e. whenever thread-specific driver state
       might have to initialized or updated.  It  can  be  NULL.   The	action
       TCL_CHANNEL_THREAD_REMOVE  is  used to notify the driver that it should
       update or remove any thread-specific data it might be  maintaining  for
       the channel.

       The  action TCL_CHANNEL_THREAD_INSERT is used to notify the driver that
       it should update or initialize any thread-specific  data	 it  might  be
       maintaining using the calling thread as the associate. See Tcl_CutChan‐
       nel and Tcl_SpliceChannel for more detail.

	      typedef void Tcl_DriverThreadActionProc(
		      ClientData instanceData,
		      int action);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       this channel was created.

       These  values  can be retrieved with Tcl_ChannelThreadActionProc, which
       returns a pointer to the function.

   TRUNCATEPROC
       The truncateProc field contains the address of the function  called  by
       the generic layer when a channel is truncated to some length. It can be
       NULL.

	      typedef int Tcl_DriverTruncateProc(
		      ClientData instanceData,
		      Tcl_WideInt length);

       InstanceData is the same as the value passed to Tcl_CreateChannel  when
       this  channel was created, and length is the new length of the underly‐
       ing file, which should not be negative. The result should be 0 on  suc‐
       cess or an errno code (suitable for use with Tcl_SetErrno) on failure.

       These  values  can be retrieved with Tcl_ChannelTruncateProc, which re‐
       turns a pointer to the function.

TCL_BADCHANNELOPTION
       This procedure generates a “bad option” error message in an  (optional)
       interpreter.  It is used by channel drivers when an invalid Set/Get op‐
       tion is requested. Its purpose is to concatenate	 the  generic  options
       list  to the specific ones and factorize the generic options error mes‐
       sage string.

       It always returns TCL_ERROR

       An error message is generated in interp's result value to indicate that
       a command was invoked with a bad option.	 The message has the form
		  bad option "blah": should be one of
		  <...generic options...>+<...specific options...>
       so you get for instance:
		  bad option "-blah": should be one of -blocking,
		  -buffering, -buffersize, -eofchar, -translation,
		  -peername, or -sockname
       when called with optionList equal to “peername sockname”

       “blah”  is  the optionName argument and “<specific options>” is a space
       separated list of specific option words.	 The function takes good  care
       of  inserting minus signs before each option, commas after, and an “or”
       before the last option.

OLD CHANNEL TYPES
       The original (8.3.1 and below) Tcl_ChannelType structure	 contains  the
       following fields:

	      typedef struct Tcl_ChannelType {
		  const char *typeName;
		  Tcl_DriverBlockModeProc *blockModeProc;
		  Tcl_DriverCloseProc *closeProc;
		  Tcl_DriverInputProc *inputProc;
		  Tcl_DriverOutputProc *outputProc;
		  Tcl_DriverSeekProc *seekProc;
		  Tcl_DriverSetOptionProc *setOptionProc;
		  Tcl_DriverGetOptionProc *getOptionProc;
		  Tcl_DriverWatchProc *watchProc;
		  Tcl_DriverGetHandleProc *getHandleProc;
		  Tcl_DriverClose2Proc *close2Proc;
	      } Tcl_ChannelType;

       It  is  still possible to create channel with the above structure.  The
       internal channel code will determine the version.  It is imperative  to
       use  the	 new  Tcl_ChannelType  structure if you are creating a stacked
       channel driver, due to problems with the earlier stacked channel imple‐
       mentation (in 8.2.0 to 8.3.1).

       Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part of
       the 8.4 development cycle) the Tcl_ChannelType structure contained  the
       following fields:

	      typedef struct Tcl_ChannelType {
		  const char *typeName;
		  Tcl_ChannelTypeVersion version;
		  Tcl_DriverCloseProc *closeProc;
		  Tcl_DriverInputProc *inputProc;
		  Tcl_DriverOutputProc *outputProc;
		  Tcl_DriverSeekProc *seekProc;
		  Tcl_DriverSetOptionProc *setOptionProc;
		  Tcl_DriverGetOptionProc *getOptionProc;
		  Tcl_DriverWatchProc *watchProc;
		  Tcl_DriverGetHandleProc *getHandleProc;
		  Tcl_DriverClose2Proc *close2Proc;
		  Tcl_DriverBlockModeProc *blockModeProc;
		  Tcl_DriverFlushProc *flushProc;
		  Tcl_DriverHandlerProc *handlerProc;
		  Tcl_DriverTruncateProc *truncateProc;
	      } Tcl_ChannelType;

       When  the  above structure is registered as a channel type, the version
       field should always be TCL_CHANNEL_VERSION_2.

SEE ALSO
       Tcl_Close(3),	     Tcl_OpenFileChannel(3),	      Tcl_SetErrno(3),
       Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)

KEYWORDS
       blocking, channel driver, channel registration, channel type, nonblock‐
       ing



Tcl				      8.4		  Tcl_CreateChannel(3)

Tcl_TraceCommand(3)	    Tcl Library Procedures	   Tcl_TraceCommand(3)



______________________________________________________________________________

NAME
       Tcl_CommandTraceInfo,  Tcl_TraceCommand,	 Tcl_UntraceCommand  - monitor
       renames and deletes of a command

SYNOPSIS
       #include <tcl.h>

       ClientData
       Tcl_CommandTraceInfo(interp, cmdName, flags, proc, prevClientData)

       int
       Tcl_TraceCommand(interp, cmdName, flags, proc, clientData)

       void
       Tcl_UntraceCommand(interp, cmdName, flags, proc, clientData)

ARGUMENTS
       Tcl_Interp *interp (in)				 Interpreter  contain‐
							 ing the command.

       const char *cmdName (in)				 Name of command.

       int flags (in)					 OR'ed	collection  of
							 the		values
							 TCL_TRACE_RENAME  and
							 TCL_TRACE_DELETE.

       Tcl_CommandTraceProc *proc (in)			 Procedure   to	  call
							 when specified opera‐
							 tions occur  to  cmd‐
							 Name.

       ClientData clientData (in)			 Arbitrary argument to
							 pass to proc.

       ClientData prevClientData (in)			 If  non-NULL,	 gives
							 last  value  returned
							 by  Tcl_CommandTrace‐
							 Info,	so  this  call
							 will return  informa‐
							 tion	 about	  next
							 trace.	 If NULL, this
							 call  will return in‐
							 formation about first
							 trace.
______________________________________________________________________________

DESCRIPTION
       Tcl_TraceCommand	 allows	 a C procedure to monitor operations performed
       on a Tcl command, so that the C procedure is invoked whenever the  com‐
       mand  is renamed or deleted.  If the trace is created successfully then
       Tcl_TraceCommand returns TCL_OK. If an  error  occurred	(e.g.  cmdName
       specifies a non-existent command) then TCL_ERROR is returned and an er‐
       ror message is left in the interpreter's result.

       The flags argument to Tcl_TraceCommand indicates when the trace	proce‐
       dure  is	 to be invoked.	 It consists of an OR'ed combination of any of
       the following values:

       TCL_TRACE_RENAME
	      Invoke proc whenever the command is renamed.

       TCL_TRACE_DELETE
	      Invoke proc when the command is deleted.

       Whenever one of the specified operations occurs to  the	command,  proc
       will  be	 invoked.   It should have arguments and result that match the
       type Tcl_CommandTraceProc:

	      typedef void Tcl_CommandTraceProc(
		      ClientData clientData,
		      Tcl_Interp *interp,
		      const char *oldName,
		      const char *newName,
		      int flags);

       The clientData and interp parameters will have the same values as those
       passed to Tcl_TraceCommand when the trace was created.  ClientData typ‐
       ically points to an application-specific data structure that  describes
       what to do when proc is invoked.	 OldName gives the name of the command
       being renamed, and newName gives the name that the command is being re‐
       named  to  (or  NULL  when  the command is being deleted.)  Flags is an
       OR'ed combination of bits potentially providing several pieces  of  in‐
       formation.   One of the bits TCL_TRACE_RENAME and TCL_TRACE_DELETE will
       be set in flags to indicate which operation is being performed  on  the
       command.	 The bit TCL_TRACE_DESTROYED will be set in flags if the trace
       is about to be destroyed; this information may be  useful  to  proc  so
       that  it can clean up its own internal data structures (see the section
       TCL_TRACE_DESTROYED below for more details).  Because the  deletion  of
       commands can take place as part of the deletion of the interp that con‐
       tains them, proc must be careful about checking what the passed in  in‐
       terp  value can be called upon to do.  The routine Tcl_InterpDeleted is
       an important tool for this.  When  Tcl_InterpDeleted  returns  1,  proc
       will not be able to invoke any scripts in interp.  The function of proc
       in that circumstance is limited to the cleanup of its own  data	struc‐
       tures.

       Tcl_UntraceCommand may be used to remove a trace.  If the command spec‐
       ified by interp, cmdName, and flags has a trace set with	 flags,	 proc,
       and  clientData,	 then  the corresponding trace is removed.  If no such
       trace exists, then the call to Tcl_UntraceCommand has no	 effect.   The
       same bits are valid for flags as for calls to Tcl_TraceCommand.

       Tcl_CommandTraceInfo  may  be used to retrieve information about traces
       set on a given command.	The return value from Tcl_CommandTraceInfo  is
       the  clientData	associated with a particular trace.  The trace must be
       on the command specified by the interp, cmdName,	 and  flags  arguments
       (note  that  currently  the flags are ignored; flags should be set to 0
       for future compatibility) and its trace procedure must the same as  the
       proc  argument.	If the prevClientData argument is NULL then the return
       value corresponds to the first (most recently created) matching	trace,
       or  NULL	 if there are no matching traces.  If the prevClientData argu‐
       ment is not NULL, then it should be the return value  from  a  previous
       call  to Tcl_CommandTraceInfo.  In this case, the new return value will
       correspond to the next matching trace after the	one  whose  clientData
       matches	prevClientData,	 or NULL if no trace matches prevClientData or
       if there are no more matching traces after it.  This mechanism makes it
       possible	 to  step  through  all of the traces for a given command that
       have the same proc.

CALLING COMMANDS DURING TRACES
       During rename traces, the command being renamed is  visible  with  both
       names  simultaneously,  and  the	 command  still	 exists	 during delete
       traces, unless the interp that contains it is being deleted.   However,
       there  is  no mechanism for signaling that an error occurred in a trace
       procedure, so great care	 should	 be  taken  that  errors  do  not  get
       silently lost.

MULTIPLE TRACES
       It  is possible for multiple traces to exist on the same command.  When
       this happens, all of the trace procedures will be invoked on  each  ac‐
       cess,  in  order	 from most-recently-created to least-recently-created.
       Attempts to  delete  the	 command  during  a  delete  trace  will  fail
       silently,  since	 the command is already scheduled for deletion anyway.
       If the command being renamed is renamed by one of  its  rename  traces,
       that  renaming  takes  precedence over the one that triggered the trace
       and the collection of traces will not be reexecuted; if several	traces
       rename the command, the last renaming takes precedence.

TCL_TRACE_DESTROYED FLAG
       In  a  delete  callback	to proc, the TCL_TRACE_DESTROYED bit is set in
       flags.

KEYWORDS
       clientData, trace, command



Tcl				      7.4		   Tcl_TraceCommand(3)

Threads(3)		    Tcl Library Procedures		    Threads(3)



______________________________________________________________________________

NAME
       Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_Get‐
       ThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_Cre‐
       ateThread, Tcl_JoinThread - Tcl thread support

SYNOPSIS
       #include <tcl.h>

       void
       Tcl_ConditionNotify(condPtr)

       void
       Tcl_ConditionWait(condPtr, mutexPtr, timePtr)

       void
       Tcl_ConditionFinalize(condPtr)

       Void *
       Tcl_GetThreadData(keyPtr, size)

       void
       Tcl_MutexLock(mutexPtr)

       void
       Tcl_MutexUnlock(mutexPtr)

       void
       Tcl_MutexFinalize(mutexPtr)

       int
       Tcl_CreateThread(idPtr, proc, clientData, stackSize, flags)

       int
       Tcl_JoinThread(id, result)

ARGUMENTS
       Tcl_Condition *condPtr (in)	       A   condition  variable,	 which
					       must be associated with a mutex
					       lock.

       Tcl_Mutex *mutexPtr (in)		       A mutex lock.

       const Tcl_Time *timePtr (in)	       A  time	limit on the condition
					       wait.  NULL  to	wait  forever.
					       Note  that a polling value of 0
					       seconds	does  not  make	  much
					       sense.

       Tcl_ThreadDataKey *keyPtr (in)	       This   identifies  a  block  of
					       thread local storage.  The  key
					       should  be  static and process-
					       wide, yet each thread will  end
					       up   associating	  a  different
					       block of storage with this key.

       int *size (in)			       The size of  the	 thread	 local
					       storage	block.	This amount of
					       data is allocated and  initial‐
					       ized  to	 zero  the  first time
					       each  thread   calls   Tcl_Get‐
					       ThreadData.

       Tcl_ThreadId *idPtr (out)	       The  referred storage will con‐
					       tain the id of the  newly  cre‐
					       ated  thread as returned by the
					       operating system.

       Tcl_ThreadId id (in)		       Id of the thread waited upon.

       Tcl_ThreadCreateProc *proc (in)	       This procedure will act as  the
					       main()  of  the	newly  created
					       thread. The  specified  client‐
					       Data will be its sole argument.

       ClientData clientData (in)	       Arbitrary  information.	Passed
					       as sole argument to the proc.

       int stackSize (in)		       The size of the stack given  to
					       the new thread.

       int flags (in)			       Bitmask containing flags allow‐
					       ing the caller to modify behav‐
					       ior of the new thread.

       int *result (out)		       The referred storage is used to
					       place  the  exit	 code  of  the
					       thread waited upon into it.
______________________________________________________________________________

INTRODUCTION
       Beginning  with the 8.1 release, the Tcl core is thread safe, which al‐
       lows you to incorporate Tcl  into  multithreaded	 applications  without
       customizing  the	 Tcl  core.  Starting with the 8.6 release, Tcl multi‐
       threading support is on by default. To disable Tcl multithreading  sup‐
       port,  you  must include the --disable-threads option to configure when
       you configure and compile your Tcl core.

       An important constraint of the Tcl threads implementation is that  only
       the thread that created a Tcl interpreter can use that interpreter.  In
       other words, multiple threads can not access the same Tcl  interpreter.
       (However,  a  single  thread  can safely create and use multiple inter‐
       preters.)

DESCRIPTION
       Tcl provides Tcl_CreateThread for creating threads. The caller can  de‐
       termine	the  size  of the stack given to the new thread and modify the
       behavior through the supplied flags. The value TCL_THREAD_STACK_DEFAULT
       for  the	 stackSize indicates that the default size as specified by the
       operating system is to be used for the new thread. As  for  the	flags,
       currently  only	the  values TCL_THREAD_NOFLAGS and TCL_THREAD_JOINABLE
       are defined. The first of them invokes the  default  behavior  with  no
       special settings.  Using the second value marks the new thread as join‐
       able. This means that another thread  can  wait	for  the  such	marked
       thread to exit and join it.

       Restrictions: On some UNIX systems the pthread-library does not contain
       the functionality to specify the stack size of a thread. The  specified
       value  for  the	stack  size is ignored on these systems.  Windows cur‐
       rently does not support joinable threads. This flag value is  therefore
       ignored on this platform.

       Tcl  provides  the  Tcl_ExitThread and Tcl_FinalizeThread functions for
       terminating threads and invoking	 optional  per-thread  exit  handlers.
       See the Tcl_Exit page for more information on these procedures.

       The  Tcl_JoinThread  function is provided to allow threads to wait upon
       the exit of another thread, which must have  been  marked  as  joinable
       through	usage  of the TCL_THREAD_JOINABLE-flag during its creation via
       Tcl_CreateThread.

       Trying to wait for the exit of a non-joinable thread or a thread	 which
       is  already waited upon will result in an error. Waiting for a joinable
       thread which already exited is possible, the  system  will  retain  the
       necessary  information  until  after  the call to Tcl_JoinThread.  This
       means that not calling Tcl_JoinThread for a joinable thread will	 cause
       a memory leak.

       The  Tcl_GetThreadData call returns a pointer to a block of thread-pri‐
       vate data.  Its argument is a key that is shared by all threads	and  a
       size  for the block of storage.	The storage is automatically allocated
       and initialized to all zeros the first time each thread	asks  for  it.
       The storage is automatically deallocated by Tcl_FinalizeThread.

   SYNCHRONIZATION AND COMMUNICATION
       Tcl  provides  Tcl_ThreadQueueEvent  and	 Tcl_ThreadAlert  for handling
       event queuing in multithreaded applications.  See the  Notifier	manual
       page for more information on these procedures.

       A mutex is a lock that is used to serialize all threads through a piece
       of code by calling Tcl_MutexLock and Tcl_MutexUnlock.   If  one	thread
       holds  a mutex, any other thread calling Tcl_MutexLock will block until
       Tcl_MutexUnlock is called.  A mutex can be destroyed after its  use  by
       calling	Tcl_MutexFinalize.   The  result of locking a mutex twice from
       the same thread is undefined.  On some platforms it will	 result	 in  a
       deadlock.   The	Tcl_MutexLock,	Tcl_MutexUnlock	 and Tcl_MutexFinalize
       procedures are defined as empty macros if not  compiling	 with  threads
       enabled.	 For declaration of mutexes the TCL_DECLARE_MUTEX macro should
       be used.	 This macro assures correct mutex handling even when the  core
       is compiled without threads enabled.

       A  condition  variable  is  used as a signaling mechanism: a thread can
       lock a mutex and then wait on a condition variable with	Tcl_Condition‐
       Wait.   This  atomically releases the mutex lock and blocks the waiting
       thread until another thread calls Tcl_ConditionNotify.  The  caller  of
       Tcl_ConditionNotify should have the associated mutex held by previously
       calling Tcl_MutexLock, but this is not enforced.	 Notifying the	condi‐
       tion  variable  unblocks all threads waiting on the condition variable,
       but they do not proceed until the mutex is released  with  Tcl_MutexUn‐
       lock.   The implementation of Tcl_ConditionWait automatically locks the
       mutex before returning.

       The caller of Tcl_ConditionWait should be prepared for spurious notifi‐
       cations	by  calling  Tcl_ConditionWait	within a while loop that tests
       some invariant.

       A condition variable can be destroyed after its use by calling Tcl_Con‐
       ditionFinalize.

       The  Tcl_ConditionNotify,  Tcl_ConditionWait  and Tcl_ConditionFinalize
       procedures are defined as empty macros if not  compiling	 with  threads
       enabled.

   INITIALIZATION
       All  of	these synchronization objects are self-initializing.  They are
       implemented as opaque pointers that should be NULL upon first use.  The
       mutexes	and  condition variables are either cleaned up by process exit
       handlers (if living that long) or explicitly by calls  to  Tcl_MutexFi‐
       nalize  or  Tcl_ConditionFinalize.   Thread  local storage is reclaimed
       during Tcl_FinalizeThread.

SCRIPT-LEVEL ACCESS TO THREADS
       Tcl provides no built-in commands for scripts to use to create, manage,
       or  join	 threads,  nor	any  script-level access to mutex or condition
       variables.  It provides such facilities	only  via  C  interfaces,  and
       leaves  it  up to packages to expose these matters to the script level.
       One such package is the Thread package.

EXAMPLE
       To create a thread with	portable  code,	 its  implementation  function
       should be declared as follows:

	      static Tcl_ThreadCreateProc MyThreadImplFunc;

       It  should then be defined like this example, which just counts up to a
       given value and then finishes.

	      static Tcl_ThreadCreateType
	      MyThreadImplFunc(
		  ClientData clientData)
	      {
		  int i, limit = (int) clientData;
		  for (i=0 ; i<limit ; i++) {
		      /* doing nothing at all here */
		  }
		  TCL_THREAD_CREATE_RETURN;
	      }

       To create the above thread, make it execute, and wait for it to finish,
       we would do this:

	      int limit = 1000000000;
	      ClientData limitData = (void*)((intptr_t) limit);
	      Tcl_ThreadId id;	  /* holds identity of thread created */
	      int result;

	      if (Tcl_CreateThread(&id, MyThreadImplFunc, limitData,
		      TCL_THREAD_STACK_DEFAULT,
		      TCL_THREAD_JOINABLE) != TCL_OK) {
		  /* Thread did not create correctly */
		  return;
	      }
	      /* Do something else for a while here */
	      if (Tcl_JoinThread(id, &result) != TCL_OK) {
		  /* Thread did not finish properly */
		  return;
	      }
	      /* All cleaned up nicely */

SEE ALSO
       Tcl_GetCurrentThread(3),	 Tcl_ThreadQueueEvent(3),  Tcl_ThreadAlert(3),
       Tcl_ExitThread(3),      Tcl_FinalizeThread(3),	   Tcl_CreateThreadEx‐
       itHandler(3), Tcl_DeleteThreadExitHandler(3), Thread

KEYWORDS
       thread, mutex, condition variable, thread local storage



Tcl				      8.1			    Threads(3)

Filesystem(3)		    Tcl Library Procedures		 Filesystem(3)



______________________________________________________________________________

NAME
       Tcl_FSRegister,	 Tcl_FSUnregister,   Tcl_FSData,  Tcl_FSMountsChanged,
       Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile,  Tcl_FS‐
       CopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDi‐
       rectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile,  Tcl_FSE‐
       valFileEx,  Tcl_FSLoadFile,  Tcl_FSUnloadFile,  Tcl_FSMatchInDirectory,
       Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAt‐
       trsSet,	Tcl_FSFileAttrStrings,	Tcl_FSStat,  Tcl_FSAccess, Tcl_FSOpen‐
       FileChannel,    Tcl_FSGetCwd,	 Tcl_FSChdir,	  Tcl_FSPathSeparator,
       Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalized‐
       Path, Tcl_FSJoinToPath, Tcl_FSConvertToPathType,	 Tcl_FSGetInternalRep,
       Tcl_FSGetTranslatedPath,	  Tcl_FSGetTranslatedStringPath,  Tcl_FSNewNa‐
       tivePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_GetAccessTime‐
       FromStat,	Tcl_GetBlockSizeFromStat,	Tcl_GetBlocksFromStat,
       Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat,  Tcl_GetFSDevice‐
       FromStat,	Tcl_GetFSInodeFromStat,	       Tcl_GetGroupIdFromStat,
       Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTime‐
       FromStat,  Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, Tcl_AllocStatBuf
       - procedures to interact with any filesystem

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_FSRegister(clientData, fsPtr)

       int
       Tcl_FSUnregister(fsPtr)

       void *
       Tcl_FSData(fsPtr)

       Tcl_FSMountsChanged(fsPtr)

       const Tcl_Filesystem *
       Tcl_FSGetFileSystemForPath(pathPtr)

       Tcl_PathType
       Tcl_FSGetPathType(pathPtr)

       int
       Tcl_FSCopyFile(srcPathPtr, destPathPtr)

       int
       Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)

       int
       Tcl_FSCreateDirectory(pathPtr)

       int
       Tcl_FSDeleteFile(pathPtr)

       int
       Tcl_FSRemoveDirectory(pathPtr, recursive, errorPtr)

       int
       Tcl_FSRenameFile(srcPathPtr, destPathPtr)

       Tcl_Obj *
       Tcl_FSListVolumes(void)

       int
       Tcl_FSEvalFileEx(interp, pathPtr, encodingName)

       int
       Tcl_FSEvalFile(interp, pathPtr)

       int
       Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
		      loadHandlePtr, unloadProcPtr)

       int								       │
       Tcl_FSUnloadFile(interp, loadHandle)				       │

       int
       Tcl_FSMatchInDirectory(interp, resultPtr, pathPtr, pattern, types)

       Tcl_Obj *
       Tcl_FSLink(linkNamePtr, toPtr, linkAction)

       int
       Tcl_FSLstat(pathPtr, statPtr)

       int
       Tcl_FSUtime(pathPtr, tval)

       int
       Tcl_FSFileAttrsGet(interp, index, pathPtr, objPtrRef)

       int
       Tcl_FSFileAttrsSet(interp, index, pathPtr, objPtr)

       const char *const *
       Tcl_FSFileAttrStrings(pathPtr, objPtrRef)

       int
       Tcl_FSStat(pathPtr, statPtr)

       int
       Tcl_FSAccess(pathPtr, mode)

       Tcl_Channel
       Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)

       Tcl_Obj *
       Tcl_FSGetCwd(interp)

       int
       Tcl_FSChdir(pathPtr)

       Tcl_Obj *
       Tcl_FSPathSeparator(pathPtr)

       Tcl_Obj *
       Tcl_FSJoinPath(listObj, elements)

       Tcl_Obj *
       Tcl_FSSplitPath(pathPtr, lenPtr)

       int
       Tcl_FSEqualPaths(firstPtr, secondPtr)

       Tcl_Obj *
       Tcl_FSGetNormalizedPath(interp, pathPtr)

       Tcl_Obj *
       Tcl_FSJoinToPath(basePtr, objc, objv)

       int
       Tcl_FSConvertToPathType(interp, pathPtr)

       void *
       Tcl_FSGetInternalRep(pathPtr, fsPtr)

       Tcl_Obj *
       Tcl_FSGetTranslatedPath(interp, pathPtr)

       const char *
       Tcl_FSGetTranslatedStringPath(interp, pathPtr)

       Tcl_Obj *
       Tcl_FSNewNativePath(fsPtr, clientData)

       const void *
       Tcl_FSGetNativePath(pathPtr)

       Tcl_Obj *
       Tcl_FSFileSystemInfo(pathPtr)

       Tcl_StatBuf *
       Tcl_AllocStatBuf()

       Tcl_WideInt							       │
       Tcl_GetAccessTimeFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetBlockSizeFromStat(statPtr)				       │

       Tcl_WideUInt							       │
       Tcl_GetBlocksFromStat(statPtr)					       │

       Tcl_WideInt							       │
       Tcl_GetChangeTimeFromStat(statPtr)				       │

       int								       │
       Tcl_GetDeviceTypeFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetFSDeviceFromStat(statPtr)					       │

       unsigned								       │
       Tcl_GetFSInodeFromStat(statPtr)					       │

       int								       │
       Tcl_GetGroupIdFromStat(statPtr)					       │

       int								       │
       Tcl_GetLinkCountFromStat(statPtr)				       │

       unsigned								       │
       Tcl_GetModeFromStat(statPtr)					       │

       Tcl_WideInt							       │
       Tcl_GetModificationTimeFromStat(statPtr)				       │

       Tcl_WideUInt							       │
       Tcl_GetSizeFromStat(statPtr)					       │

       int								       │
       Tcl_GetUserIdFromStat(statPtr)					       │

ARGUMENTS
       const Tcl_Filesystem *fsPtr (in)		   Points to a structure  con‐
						   taining  the	 addresses  of
						   procedures  that   can   be
						   called to perform the vari‐
						   ous filesystem operations.

       Tcl_Obj *pathPtr (in)			   The	path  represented   by
						   this	 value is used for the
						   operation in	 question.  If
						   the	value does not already
						   have an internal path  rep‐
						   resentation,	  it  will  be
						   converted to have one.

       Tcl_Obj *srcPathPtr (in)			   As for  pathPtr,  but  used
						   for	the  source file for a
						   copy or rename operation.

       Tcl_Obj *destPathPtr (in)		   As for  pathPtr,  but  used
						   for	the  destination file‐
						   name for a copy  or	rename
						   operation.

       int recursive (in)			   Whether to remove subdirec‐
						   tories and  their  contents
						   as well.

       const char *encodingName (in)		   The	encoding  of  the data
						   stored in the file  identi‐
						   fied	 by  pathPtr and to be
						   evaluated.

       const char *pattern (in)			   Only files  or  directories
						   matching  this pattern will
						   be returned.

       Tcl_GlobTypeData *types (in)		   Only files  or  directories
						   matching  the type descrip‐
						   tions  contained  in	  this
						   structure will be returned.
						   This parameter may be NULL.

       Tcl_Interp *interp (in)			   Interpreter to  use	either
						   for results, evaluation, or
						   reporting error messages.

       void *clientData (in)			   The native  description  of
						   the path value to create.

       Tcl_Obj *firstPtr (in)			   The	first of two path val‐
						   ues to compare.  The	 value
						   may	be  converted  to path
						   type.

       Tcl_Obj *secondPtr (in)			   The second of two path val‐
						   ues	to  compare. The value
						   may be  converted  to  path
						   type.

       Tcl_Obj *listObj (in)			   The	list  of path elements
						   to operate on with  a  join
						   operation.

       int elements (in)			   The	number	of elements in
						   the listObj which should be
						   joined  together.  If nega‐
						   tive, then all elements are
						   joined.

       Tcl_Obj **errorPtr (out)			   In  the  case  of an error,
						   filled with	a  value  con‐
						   taining  the	 name  of  the
						   file which caused an	 error
						   in  the various copy/rename
						   operations.

       int index (in)				   The index of the  attribute
						   in question.

       Tcl_Obj *objPtr (in)			   The value to set in the op‐
						   eration.

       Tcl_Obj **objPtrRef (out)		   Filled with	a  value  con‐
						   taining  the	 result of the
						   operation.

       Tcl_Obj *resultPtr (out)			   Preallocated value in which
						   to store (using Tcl_ListOb‐
						   jAppendElement) the list of
						   files  or directories which
						   are successfully matched.

       int mode (in)				   Mask consisting of  one  or
						   more	 of  R_OK,  W_OK, X_OK
						   and F_OK.  R_OK,  W_OK  and
						   X_OK	   request    checking
						   whether the file exists and
						   has	 read, write and  exe‐
						   cute	 permissions,  respec‐
						   tively.  F_OK just requests
						   checking for the  existence
						   of the file.

       Tcl_StatBuf *statPtr (out)		   The structure that contains
						   the result  of  a  stat  or
						   lstat operation.

       const char *sym1 (in)			   Name of a procedure to look
						   up in the file's symbol ta‐
						   ble

       const char *sym2 (in)			   Name of a procedure to look
						   up in the file's symbol ta‐
						   ble

       Tcl_PackageInitProc **proc1Ptr (out)	   Filled  with the init func‐
						   tion for this code.

       Tcl_PackageInitProc **proc2Ptr (out)	   Filled with	the  safe-init
						   function for this code.

       void **clientDataPtr (out)		   Filled  with the clientData
						   value  to  pass   to	  this
						   code's unload function when
						   it is called.

       Tcl_LoadHandle *loadHandlePtr (out)	   Filled with an abstract to‐
						   ken representing the loaded
						   file.

       Tcl_FSUnloadFileProc **unloadProcPtr (out)  Filled with the function to
						   use to unload this piece of
						   code.

       Tcl_LoadHandle loadHandle (in)		   Handle to  the  loaded  li‐
						   brary to be unloaded.

       utimbuf *tval (in)			   The access and modification
						   times in this structure are
						   read	 and used to set those
						   values for a given file.

       const char *modeString (in)		   Specifies how the  file  is
						   to  be  accessed.  May have
						   any of the  values  allowed
						   for	the  mode  argument to
						   the Tcl open command.

       int permissions (in)			   POSIX-style	    permission
						   flags  such	as  0644. If a
						   new file is created,	 these
						   permissions	will be set on
						   the created file.

       int *lenPtr (out)			   If  non-NULL,  filled  with
						   the	number	of elements in
						   the split path.

       Tcl_Obj *basePtr (in)			   The base path on  to	 which
						   to join the given elements.
						   May be NULL.

       int objc (in)				   The number of  elements  in
						   objv.

       Tcl_Obj *const objv[] (in)		   The elements to join to the
						   given base path.

       Tcl_Obj *linkNamePtr (in)		   The name of the link to  be
						   created or read.

       Tcl_Obj *toPtr (in)			   What	   the	 link	called
						   linkNamePtr	  should    be
						   linked  to,	or NULL if the
						   symbolic link specified  by
						   linkNamePtr is to be read.

       int linkAction (in)			   OR-ed  combination of flags
						   indicating  what  kind   of
						   link	  should   be  created
						   (will be ignored  if	 toPtr
						   is NULL). Valid bits to set
						   are	       TCL_CREATE_SYM‐
						   BOLIC_LINK	and   TCL_CRE‐
						   ATE_HARD_LINK.   When  both
						   flags  are  set and the un‐
						   derlying filesystem can  do
						   either,  symbolic links are
						   preferred.
______________________________________________________________________________

DESCRIPTION
       There  are  several  reasons  for  calling  the	Tcl_FS	API  functions
       (e.g. Tcl_FSAccess  and	Tcl_FSStat)  rather  than calling system level
       functions like access and stat directly. First, they will  work	cross-
       platform,  so  an  extension which calls them should work unmodified on
       Unix and Windows. Second, the Windows implementation of some  of	 these
       functions fixes some bugs in the system level calls. Third, these func‐
       tion calls deal with any	 “Utf  to  platform-native”  path  conversions
       which  may  be  required (and may cache the results of such conversions
       for greater efficiency on subsequent calls). Fourth, and	 perhaps  most
       importantly,  all  of  these  functions are “virtual filesystem aware”.
       Any virtual filesystem  (VFS  for  short)  which	 has  been  registered
       (through	 Tcl_FSRegister)  may reroute file access to alternative media
       or access methods. This means that all of these functions  (and	there‐
       fore  the  corresponding	 file, glob, pwd, cd, open, etc. Tcl commands)
       may be operate on “files” which are not	native	files  in  the	native
       filesystem.  This  also means that any Tcl extension which accesses the
       filesystem (FS for short) through this API  is  automatically  “virtual
       filesystem  aware”.   Of	 course,  if  an extension accesses the native
       filesystem directly (through platform-specific APIs, for example), then
       Tcl cannot intercept such calls.

       If appropriate VFSes have been registered, the “files” may, to give two
       examples, be remote (e.g. situated on a remote ftp server) or  archived
       (e.g. lying inside a .zip archive). Such registered filesystems provide
       a lookup table of functions to implement all or some of the functional‐
       ity listed here. Finally, the Tcl_FSStat and Tcl_FSLstat calls abstract
       away from what the “struct stat” buffer is actually declared to be, al‐
       lowing  the same code to be used both on systems with and systems with‐
       out support for files larger than 2GB in size.

       The Tcl_FS API is Tcl_Obj-ified and may cache internal  representations
       and  other  path-related	 strings (e.g. the current working directory).
       One side-effect of this is that one must not pass in values with a ref‐
       erence count of zero to any of these functions. If such calls were han‐
       dled, they might result in memory leaks (under some circumstances,  the
       filesystem  code may wish to retain a reference to the passed in value,
       and so one must not assume that after any of these  calls  return,  the
       value  still  has  a  reference count of zero - it may have been incre‐
       mented) or in a direct segmentation fault (or other memory  access  er‐
       ror)  due  to  the value being freed part way through the complex value
       manipulation required to ensure that the path is fully  normalized  and
       absolute	 for  filesystem  determination. The practical lesson to learn
       from this is that

	      Tcl_Obj *path = Tcl_NewStringObj(...);
	      Tcl_FSWhatever(path);
	      Tcl_DecrRefCount(path);

       is wrong, and may cause memory errors. The path must have its reference
       count  incremented  before  passing it in, or decrementing it. For this
       reason, values with a reference count of zero are considered not to  be
       valid  filesystem paths and calling any Tcl_FS API function with such a
       value will result in no action being taken.

   FS API FUNCTIONS
       Tcl_FSCopyFile attempts to copy the file given  by  srcPathPtr  to  the
       path  name given by destPathPtr. If the two paths given lie in the same
       filesystem (according to Tcl_FSGetFileSystemForPath) then that filesys‐
       tem's  “copy  file”  function is called (if it is non-NULL).  Otherwise
       the function returns -1 and sets the errno global  C  variable  to  the
       “EXDEV” POSIX error code (which signifies a “cross-domain link”).

       Tcl_FSCopyDirectory  attempts to copy the directory given by srcPathPtr
       to the path name given by destPathPtr. If the two paths	given  lie  in
       the same filesystem (according to Tcl_FSGetFileSystemForPath) then that
       filesystem's “copy file” function is called (if it is non-NULL).	  Oth‐
       erwise  the function returns -1 and sets the errno global C variable to
       the “EXDEV” POSIX error code (which signifies a “cross-domain link”).

       Tcl_FSCreateDirectory attempts to create the directory given by pathPtr
       by calling the owning filesystem's “create directory” function.

       Tcl_FSDeleteFile	 attempts to delete the file given by pathPtr by call‐
       ing the owning filesystem's “delete file” function.

       Tcl_FSRemoveDirectory attempts to remove the directory given by pathPtr
       by calling the owning filesystem's “remove directory” function.

       Tcl_FSRenameFile attempts to rename the file or directory given by src‐
       PathPtr to the path name given by destPathPtr. If the two  paths	 given
       lie  in	the  same filesystem (according to Tcl_FSGetFileSystemForPath)
       then that filesystem's “rename file” function is called (if it is  non-
       NULL).  Otherwise  the  function returns -1 and sets the errno global C
       variable to the “EXDEV” POSIX error code (which signifies a  “cross-do‐
       main link”).

       Tcl_FSListVolumes calls each filesystem which has a non-NULL “list vol‐
       umes” function and asks them to return their list of root  volumes.  It
       accumulates the return values in a list which is returned to the caller
       (with a reference count of 0).

       Tcl_FSEvalFileEx reads the file given by	 pathPtr  using	 the  encoding
       identified  by encodingName and evaluates its contents as a Tcl script.
       It returns the same information as Tcl_EvalObjEx.  If  encodingName  is
       NULL,  the  system  encoding is used for reading the file contents.  If
       the file could not be read then a Tcl error is returned to describe why
       the  file  could not be read.  The eofchar for files is “\x1A” (^Z) for
       all platforms.  If you require a “^Z” in code  for  string  comparison,
       you  can use “\x1A”, which will be safely substituted by the Tcl inter‐
       preter into “^Z”.  Tcl_FSEvalFile is a simpler version  of  Tcl_FSEval‐
       FileEx that always uses the system encoding when reading the file.

       Tcl_FSLoadFile dynamically loads a binary code file into memory and re‐
       turns the addresses of two procedures within that file, if they are de‐
       fined. The appropriate function for the filesystem to which pathPtr be‐
       longs will be called. If that filesystem does not implement this	 func‐
       tion  (most  virtual filesystems will not, because of OS limitations in
       dynamically loading binary code), Tcl will attempt to copy the file  to
       a  temporary  directory and load that temporary file.  Tcl_FSUnloadFile │
       reverses the operation, asking for the library indicated by  the	 load‐ │
       Handle  to  be removed from the process. Note that, unlike with the un‐ │
       load command, this does not give the library any opportunity  to	 clean │
       up.

       Both  the  above functions return a standard Tcl completion code. If an
       error occurs, an error message is left in the interp's result.

       The token provided via the variable indicated by loadHandlePtr  may  be │
       used with Tcl_FindSymbol.

       Tcl_FSMatchInDirectory  is used by the globbing code to search a direc‐
       tory for all files which match a given pattern. The  appropriate	 func‐
       tion for the filesystem to which pathPtr belongs will be called.

       The  return  value is a standard Tcl result indicating whether an error
       occurred in globbing. Error messages are placed in interp  (unless  in‐
       terp is NULL, which is allowed), but good results are placed in the re‐
       sultPtr given.

       Note that the glob code implements recursive  patterns  internally,  so
       this  function  will  only ever be passed simple patterns, which can be
       matched using the logic of string match. To handle recursion, Tcl  will
       call  this  function  frequently	 asking only for directories to be re‐
       turned. A special case of being called with a  NULL  pattern  indicates
       that the path needs to be checked only for the correct type.

       Tcl_FSLink  replaces the library version of readlink, and extends it to
       support the  creation  of  links.  The  appropriate  function  for  the
       filesystem to which linkNamePtr belongs will be called.

       If  the toPtr is NULL, a “read link” action is performed. The result is
       a Tcl_Obj specifying  the  contents  of	the  symbolic  link  given  by
       linkNamePtr, or NULL if the link could not be read. The result is owned
       by the caller, which should call Tcl_DecrRefCount when the result is no
       longer  needed.	If  the toPtr is not NULL, Tcl should create a link of
       one of the types passed in in the linkAction flag.   This  flag	is  an
       OR'ed combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CREATE_HARD_LINK.
       Where a choice exists (i.e. more than one flag is passed in),  the  Tcl
       convention  is  to  prefer  symbolic links. When a link is successfully
       created, the return value should be toPtr (which is  therefore  already
       owned by the caller). If unsuccessful, NULL is returned.

       Tcl_FSLstat  fills  the	Tcl_StatBuf structure statPtr with information
       about the specified file. You do not need any access rights to the file
       to  get	this information but you need search rights to all directories
       named in the path leading to the file. The  Tcl_StatBuf	structure  in‐
       cludes  info  regarding	device, inode (always 0 on Windows), privilege
       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
       id  (always 0 on Windows), rdev (same as device on Windows), size, last
       access time, last modification time, and	 last  metadata	 change	 time.
       See PORTABLE STAT RESULT API for a description of how to write portable
       code to allocate and access the Tcl_StatBuf structure.

       If path exists, Tcl_FSLstat returns 0 and the stat structure is	filled
       with data. Otherwise, -1 is returned, and no stat info is given.

       Tcl_FSUtime replaces the library version of utime.

       This  returns 0 on success and -1 on error (as per the utime documenta‐
       tion). If successful, the function will update the “atime” and  “mtime”
       values of the file given.

       Tcl_FSFileAttrsGet  implements  read  access  for the hookable file at‐
       tributes subcommand. The appropriate function  for  the	filesystem  to
       which pathPtr belongs will be called.

       If  the	result	is TCL_OK, then a value was placed in objPtrRef, which
       will only be temporarily valid (unless Tcl_IncrRefCount is called).

       Tcl_FSFileAttrsSet implements write access for the  hookable  file  at‐
       tributes	 subcommand.  The  appropriate	function for the filesystem to
       which pathPtr belongs will be called.

       Tcl_FSFileAttrStrings implements part of the hookable  file  attributes
       subcommand.  The appropriate function for the filesystem to which path‐
       Ptr belongs will be called.

       The called procedure may either return an array of strings, or may  in‐
       stead  return  NULL  and place a Tcl list into the given objPtrRef. Tcl
       will take that list and first increment its reference count before  us‐
       ing  it.	  On  completion of that use, Tcl will decrement its reference
       count. Hence if the list should be disposed of by  Tcl  when  done,  it
       should  have  a	reference count of zero, and if the list should not be
       disposed of, the filesystem should ensure it retains a reference	 count
       to the value.

       Tcl_FSAccess checks whether the process would be allowed to read, write
       or test for existence of the file (or other  filesystem	object)	 whose
       name  is pathname. If pathname is a symbolic link on Unix, then permis‐
       sions of the file referred by this symbolic link are tested.

       On success (all requested permissions granted), zero  is	 returned.  On
       error  (at least one bit in mode asked for a permission that is denied,
       or some other error occurred), -1 is returned.

       Tcl_FSStat fills the Tcl_StatBuf	 structure  statPtr  with  information
       about the specified file. You do not need any access rights to the file
       to get this information but you need search rights to  all  directories
       named  in  the  path leading to the file. The Tcl_StatBuf structure in‐
       cludes info regarding device, inode (always 0  on  Windows),  privilege
       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
       id (always 0 on Windows), rdev (same as device on Windows), size,  last
       access  time,  last  modification  time, and last metadata change time.
       See PORTABLE STAT RESULT API for a description of how to write portable
       code to allocate and access the Tcl_StatBuf structure.

       If  path	 exists, Tcl_FSStat returns 0 and the stat structure is filled
       with data. Otherwise, -1 is returned, and no stat info is given.

       Tcl_FSOpenFileChannel opens a file specified by pathPtr and  returns  a
       channel	handle	that  can  be  used to perform input and output on the
       file. This API is modeled after the fopen procedure of the  Unix	 stan‐
       dard  I/O  library.  The syntax and meaning of all arguments is similar
       to those given in the Tcl open command when opening a file.  If an  er‐
       ror  occurs  while  opening  the channel, Tcl_FSOpenFileChannel returns
       NULL and records	 a  POSIX  error  code	that  can  be  retrieved  with
       Tcl_GetErrno.   In addition, if interp is non-NULL, Tcl_FSOpenFileChan‐
       nel leaves an error message in interp's result after any error.

       The newly created channel is not	 registered  in	 the  supplied	inter‐
       preter;	to  register it, use Tcl_RegisterChannel.  If one of the stan‐
       dard channels, stdin, stdout or stderr was previously closed,  the  act
       of  creating  the  new channel also assigns it as a replacement for the
       standard channel.

       Tcl_FSGetCwd replaces the library version of getcwd.

       It returns the Tcl library's current working  directory.	 This  may  be
       different  to  the  native  platform's working directory, which happens
       when the current working directory is not in the native filesystem.

       The result is a pointer to a Tcl_Obj specifying the current  directory,
       or  NULL	 if  the current directory could not be determined. If NULL is
       returned, an error message is left in the interp's result.

       The result already has its reference count incremented for the  caller.
       When  it	 is  no	 longer	 needed, that reference count should be decre‐
       mented. This is needed for thread-safety purposes,  to  allow  multiple
       threads	to  access  this and related functions, while ensuring the re‐
       sults are always valid.

       Tcl_FSChdir replaces the library version of chdir. The path is  normal‐
       ized  and  then	passed	to  the	 filesystem  which  claims it. If that
       filesystem does not implement this function, Tcl	 will  fallback	 to  a
       combination  of	stat  and access to check whether the directory exists
       and has appropriate permissions.

       For results, see chdir documentation. If successful, we keep  a	record
       of  the	successful  path in cwdPathPtr for subsequent calls to Tcl_FS‐
       GetCwd.

       Tcl_FSPathSeparator returns the separator character to be used for most
       specific	 element  of the path specified by pathPtr (i.e. the last part
       of the path).

       The separator is returned as a Tcl_Obj containing a string of length 1.
       If the path is invalid, NULL is returned.

       Tcl_FSJoinPath  takes  the  given  Tcl_Obj,  which must be a valid list
       (which is allowed to have a reference count of zero), and  returns  the
       path  value  given  by considering the first elements elements as valid
       path segments (each path segment may be a complete path, a partial path
       or  just a single possible directory or file name). If any path segment
       is actually an absolute path, then all prior  path  segments  are  dis‐
       carded.	If elements is less than 0, we use the entire list.

       It  is  possible	 that the returned value is actually an element of the
       given list, so the caller should be careful to increment the  reference
       count of the result before freeing the list.

       The  returned  value,  typically with a reference count of zero (but it
       could be shared under some conditions), contains the joined  path.  The
       caller must add a reference count to the value before using it. In par‐
       ticular, the returned value could be an element of the given  list,  so
       freeing the list might free the value prematurely if no reference count
       has been taken.	If the number of elements is zero, then	 the  returned
       value will be an empty-string Tcl_Obj.

       Tcl_FSSplitPath	takes the given Tcl_Obj, which should be a valid path,
       and returns a Tcl list value containing each segment of that path as an
       element.	  It  returns  a list value with a reference count of zero. If
       the passed in lenPtr is non-NULL, the variable it points to will be up‐
       dated to contain the number of elements in the returned list.

       Tcl_FSEqualPaths	 tests	whether the two paths given represent the same
       filesystem object.  It returns 1 if the paths are equal, and 0 if  they
       are different. If either path is NULL, 0 is always returned.

       Tcl_FSGetNormalizedPath	attempts  to  extract from the given Tcl_Obj a
       unique normalized path representation, whose string value can  be  used
       as a unique identifier for the file.

       It returns the normalized path value, owned by Tcl, or NULL if the path
       was invalid or could otherwise not be successfully converted.   Extrac‐
       tion  of	 absolute,  normalized	paths  is  very efficient (because the
       filesystem operates on these representations internally), although  the
       result  when the filesystem contains numerous symbolic links may not be
       the most user-friendly version of a path. The return value is owned  by
       Tcl and has a lifetime equivalent to that of the pathPtr passed in (un‐
       less that is a relative path, in which case the normalized  path	 value
       may  be	freed any time the cwd changes) - the caller can of course in‐
       crement the reference count if it wishes to maintain a copy for longer.

       Tcl_FSJoinToPath takes the given value, which should usually be a valid
       path or NULL, and joins onto it the array of paths segments given.

       Returns	a  value, typically with reference count of zero (but it could
       be shared under some  conditions),  containing  the  joined  path.  The
       caller  must add a reference count to the value before using it. If any
       of the values passed into this function (pathPtr or path elements) have
       a  reference  count  of zero, they will be freed when this function re‐
       turns.

       Tcl_FSConvertToPathType tries to convert the given Tcl_Obj to  a	 valid
       Tcl path type, taking account of the fact that the cwd may have changed
       even if this value is already supposedly	 of  the  correct  type.   The
       filename may begin with “~” (to indicate current user's home directory)
       or “~<user>” (to indicate any user's home directory).

       If the conversion succeeds (i.e. the value is a valid path  in  one  of
       the  current filesystems), then TCL_OK is returned. Otherwise TCL_ERROR
       is returned, and an error message may be left in the interpreter.

       Tcl_FSGetInternalRep extracts the internal representation  of  a	 given
       path  value,  in	 the  given filesystem. If the path value belongs to a
       different filesystem, we return NULL. If the internal representation is
       currently  NULL, we attempt to generate it, by calling the filesystem's
       Tcl_FSCreateInternalRepProc.

       Returns NULL or a valid internal	 path  representation.	This  internal
       representation  is cached, so that repeated calls to this function will
       not require additional conversions.

       Tcl_FSGetTranslatedPath attempts to extract the	translated  path  from
       the given Tcl_Obj.

       If  the	translation succeeds (i.e. the value is a valid path), then it
       is returned. Otherwise NULL will be returned, and an error message  may
       be  left	 in the interpreter. A “translated” path is one which contains
       no “~” or “~user” sequences (these have been expanded to their  current
       representation  in  the filesystem). The value returned is owned by the
       caller, which must store it or call Tcl_DecrRefCount to	ensure	memory
       is  freed.  This function is of little practical use, and Tcl_FSGetNor‐
       malizedPath or Tcl_FSGetNativePath are usually better functions to  use
       for most purposes.

       Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
       but returns a character string or NULL.	The string returned is dynami‐
       cally  allocated	 and  owned by the caller, which must store it or call
       ckfree to ensure it is freed. Again, Tcl_FSGetNormalizedPath or Tcl_FS‐
       GetNativePath are usually better functions to use for most purposes.

       Tcl_FSNewNativePath  performs  something	 like the reverse of the usual
       obj->path->nativerep conversions. If some code retrieves a path in  na‐
       tive form (from, e.g. readlink or a native dialog), and that path is to
       be used at the Tcl level, then calling this function  is	 an  efficient
       way of creating the appropriate path value type.

       The  resulting  value is a pure “path” value, which will only receive a
       UTF-8 string representation if that is required by some Tcl code.

       Tcl_FSGetNativePath is for use by the Win/Unix native  filesystems,  so
       that  they can easily retrieve the native (char* or TCHAR*) representa‐
       tion of a path. This function is a convenience wrapper  around  Tcl_FS‐
       GetInternalRep.	It  may be desirable in the future to have non-string-
       based native representations (for example, on macOS,  a	representation
       using  a fileSpec of FSRef structure would probably be more efficient).
       On Windows a full Unicode representation would allow for paths  of  un‐
       limited	length.	 Currently  the	 representation	 is simply a character
       string which may contain either the relative path or a complete,	 abso‐
       lute normalized path in the native encoding (complex conditions dictate
       which of these will be provided, so neither can be relied upon,	unless
       the path is known to be absolute). If you need a native path which must
       be absolute, then you should ask for the native version of a normalized
       path.  If for some reason a non-absolute, non-normalized version of the
       path is needed, that must be constructed separately (e.g. using Tcl_FS‐
       GetTranslatedPath).

       The  native  representation  is	cached	so that repeated calls to this
       function will not require additional conversions. The return  value  is
       owned  by  Tcl  and  has	 a  lifetime equivalent to that of the pathPtr
       passed in (unless that is a relative path, in  which  case  the	native
       representation may be freed any time the cwd changes).

       Tcl_FSFileSystemInfo  returns a list of two elements. The first element
       is the name  of	the  filesystem	 (e.g.	 “native”,  “vfs”,  “zip”,  or
       “prowrap”, perhaps), and the second is the particular type of the given
       path within that filesystem (which is filesystem dependent). The second
       element may be empty if the filesystem does not provide a further cate‐
       gorization of files.

       A valid list value is returned, unless the path	value  is  not	recog‐
       nized, when NULL will be returned.

       Tcl_FSGetFileSystemForPath  returns  a  pointer	to  the Tcl_Filesystem
       which accepts this path as valid.

       If no filesystem will accept the path, NULL is returned.

       Tcl_FSGetPathType determines whether the given path is relative to  the
       current directory, relative to the current volume, or absolute.

       It    returns   one   of	  TCL_PATH_ABSOLUTE,   TCL_PATH_RELATIVE,   or
       TCL_PATH_VOLUME_RELATIVE

   PORTABLE STAT RESULT API
       Tcl_AllocStatBuf allocates a Tcl_StatBuf on the system heap (which  may
       be  deallocated	by  being passed to ckfree). This allows extensions to
       invoke Tcl_FSStat and Tcl_FSLstat without being dependent on  the  size
       of the buffer. That in turn depends on the flags used to build Tcl.

       The  portable  fields  of a Tcl_StatBuf may be read using the following │
       functions, each of which returns the value of the  corresponding	 field │
       listed  in  the	table  below. Note that on some platforms there may be │
       other fields in the Tcl_StatBuf as it is an alias for a suitable system │
       structure, but only the portable ones are made available here. See your │
       system documentation for a full description of these fields.	       │

	      Access Function			 Field			       │
	       Tcl_GetFSDeviceFromStat		  st_dev		       │
	       Tcl_GetFSInodeFromStat		  st_ino		       │
	       Tcl_GetModeFromStat		  st_mode		       │
	       Tcl_GetLinkCountFromStat		  st_nlink		       │
	       Tcl_GetUserIdFromStat		  st_uid		       │
	       Tcl_GetGroupIdFromStat		  st_gid		       │
	       Tcl_GetDeviceTypeFromStat	  st_rdev		       │
	       Tcl_GetAccessTimeFromStat	  st_atime		       │
	       Tcl_GetModificationTimeFromStat	  st_mtime		       │
	       Tcl_GetChangeTimeFromStat	  st_ctime		       │
	       Tcl_GetSizeFromStat		  st_size		       │
	       Tcl_GetBlocksFromStat		  st_blocks		       │
	       Tcl_GetBlockSizeFromStat		  st_blksize		       │


THE VIRTUAL FILESYSTEM API
       A filesystem provides a Tcl_Filesystem structure that contains pointers
       to  functions  that  implement  the various operations on a filesystem;
       these operations are invoked as needed by the generic layer, which gen‐
       erally occurs through the functions listed above.

       The Tcl_Filesystem structures are manipulated using the following meth‐
       ods.

       Tcl_FSRegister takes a pointer to a filesystem  structure  and  an  op‐
       tional  piece  of  data	to associated with that filesystem. On calling
       this function, Tcl will attach the filesystem  to  the  list  of	 known
       filesystems,  and it will become fully functional immediately. Tcl does
       not check if the same filesystem is registered multiple times  (and  in
       general that is not a good thing to do). TCL_OK will be returned.

       Tcl_FSUnregister	 removes  the given filesystem structure from the list
       of known filesystems, if it  is	known,	and  returns  TCL_OK.  If  the
       filesystem is not currently registered, TCL_ERROR is returned.

       Tcl_FSData  will	 return	 the  clientData  associated  with  the	 given
       filesystem, if that filesystem is registered. Otherwise it will	return
       NULL.

       Tcl_FSMountsChanged  is	used  to inform the Tcl's core that the set of
       mount  points  for  the	given  (already	 registered)  filesystem  have
       changed,	 and  that cached file representations may therefore no longer
       be correct.

   THE TCL_FILESYSTEM STRUCTURE
       The Tcl_Filesystem structure contains the following fields:

	      typedef struct Tcl_Filesystem {
		  const char *typeName;
		  int structureLength;
		  Tcl_FSVersion version;
		  Tcl_FSPathInFilesystemProc *pathInFilesystemProc;
		  Tcl_FSDupInternalRepProc *dupInternalRepProc;
		  Tcl_FSFreeInternalRepProc *freeInternalRepProc;
		  Tcl_FSInternalToNormalizedProc *internalToNormalizedProc;
		  Tcl_FSCreateInternalRepProc *createInternalRepProc;
		  Tcl_FSNormalizePathProc *normalizePathProc;
		  Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc;
		  Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc;
		  Tcl_FSStatProc *statProc;
		  Tcl_FSAccessProc *accessProc;
		  Tcl_FSOpenFileChannelProc *openFileChannelProc;
		  Tcl_FSMatchInDirectoryProc *matchInDirectoryProc;
		  Tcl_FSUtimeProc *utimeProc;
		  Tcl_FSLinkProc *linkProc;
		  Tcl_FSListVolumesProc *listVolumesProc;
		  Tcl_FSFileAttrStringsProc *fileAttrStringsProc;
		  Tcl_FSFileAttrsGetProc *fileAttrsGetProc;
		  Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
		  Tcl_FSCreateDirectoryProc *createDirectoryProc;
		  Tcl_FSRemoveDirectoryProc *removeDirectoryProc;
		  Tcl_FSDeleteFileProc *deleteFileProc;
		  Tcl_FSCopyFileProc *copyFileProc;
		  Tcl_FSRenameFileProc *renameFileProc;
		  Tcl_FSCopyDirectoryProc *copyDirectoryProc;
		  Tcl_FSLstatProc *lstatProc;
		  Tcl_FSLoadFileProc *loadFileProc;
		  Tcl_FSGetCwdProc *getCwdProc;
		  Tcl_FSChdirProc *chdirProc;
	      } Tcl_Filesystem;

       Except for the first three fields in this structure which contain  sim‐
       ple data elements, all entries contain addresses of functions called by
       the generic filesystem layer to perform the complete range of  filesys‐
       tem related actions.

       The  many  functions in this structure are broken down into three cate‐
       gories: infrastructure functions (almost all of which  must  be	imple‐
       mented), operational functions (which must be implemented if a complete
       filesystem is provided), and efficiency functions (which need  only  be
       implemented  if	they can be done so efficiently, or if they have side-
       effects which are required by the filesystem; Tcl  has  less  efficient
       emulations  it  can fall back on). It is important to note that, in the
       current version of Tcl, most of these fallbacks are only used to handle
       commands initiated in Tcl, not in C. What this means is, that if a file
       rename command is issued in Tcl, and the relevant filesystem(s) do  not
       implement  their Tcl_FSRenameFileProc, Tcl's core will instead fallback
       on a combination of other filesystem functions (it will use Tcl_FSCopy‐
       FileProc followed by Tcl_FSDeleteFileProc, and if Tcl_FSCopyFileProc is
       not implemented there is a further fallback). However, if  a  Tcl_FSRe‐
       nameFileProc command is issued at the C level, no such fallbacks occur.
       This is true except for the last four entries in the  filesystem	 table
       (lstat, load, getcwd and chdir) for which fallbacks do in fact occur at
       the C level.

       Any functions which take path names in Tcl_Obj form take those names in
       UTF-8  form.  The  filesystem infrastructure API is designed to support
       efficient, cached conversion of these UTF-8 paths to other native  rep‐
       resentations.

   EXAMPLE FILESYSTEM DEFINITION
       Here  is	 the filesystem lookup table used by the “vfs” extension which
       allows filesystem actions to be implemented in Tcl.

	      static Tcl_Filesystem vfsFilesystem = {
		  "tclvfs",
		  sizeof(Tcl_Filesystem),
		  TCL_FILESYSTEM_VERSION_1,
		  &VfsPathInFilesystem,
		  &VfsDupInternalRep,
		  &VfsFreeInternalRep,
		  /* No internal to normalized, since we don't create
		   * any pure 'internal' Tcl_Obj path representations */
		  NULL,
		  /* No create native rep function, since we don't use
		   * it and don't choose to support uses of
		   * Tcl_FSNewNativePath */
		  NULL,
		  /* Normalize path isn't needed - we assume paths only
		   * have one representation */
		  NULL,
		  &VfsFilesystemPathType,
		  &VfsFilesystemSeparator,
		  &VfsStat,
		  &VfsAccess,
		  &VfsOpenFileChannel,
		  &VfsMatchInDirectory,
		  &VfsUtime,
		  /* We choose not to support symbolic links inside our
		   * VFS's */
		  NULL,
		  &VfsListVolumes,
		  &VfsFileAttrStrings,
		  &VfsFileAttrsGet,
		  &VfsFileAttrsSet,
		  &VfsCreateDirectory,
		  &VfsRemoveDirectory,
		  &VfsDeleteFile,
		  /* No copy file; use the core fallback mechanism */
		  NULL,
		  /* No rename file; use the core fallback mechanism */
		  NULL,
		  /* No copy directory; use the core fallback mechanism */
		  NULL,
		  /* Core will use stat for lstat */
		  NULL,
		  /* No load; use the core fallback mechanism */
		  NULL,
		  /* We don't need a getcwd or chdir; the core's own
		   * internal value is suitable */
		  NULL,
		  NULL
	      };

FILESYSTEM INFRASTRUCTURE
       These fields contain basic information about the	 filesystem  structure
       and  addresses  of  functions  which are used to associate a particular
       filesystem with a file path, and deal with  the	internal  handling  of
       path  representations, for example copying and freeing such representa‐
       tions.

   TYPENAME
       The typeName field contains a null-terminated  string  that  identifies
       the type of the filesystem implemented, e.g.  “native”, “zip” or “vfs”.

   STRUCTURE LENGTH
       The    structureLength	 field	  is	generally    implemented    as
       sizeof(Tcl_Filesystem), and is there to allow easier  binary  backwards
       compatibility  if the size of the structure changes in a future Tcl re‐
       lease.

   VERSION
       The version field should be set to TCL_FILESYSTEM_VERSION_1.

   PATHINFILESYSTEMPROC
       The pathInFilesystemProc field contains the address of a function which
       is  called  to  determine  whether  a  given path value belongs to this
       filesystem or not. Tcl will only call the rest of the filesystem	 func‐
       tions  with a path for which this function has returned TCL_OK.	If the
       path does not belong, -1 should be returned (the behavior  of  Tcl  for
       any other return value is not defined). If TCL_OK is returned, then the
       optional clientDataPtr output parameter can be used to return an inter‐
       nal  (filesystem	 specific)  representation  of the path, which will be
       cached inside the path value, and may be retrieved efficiently  by  the
       other filesystem functions. Tcl will simultaneously cache the fact that
       this path belongs to this filesystem. Such caches are invalidated  when
       filesystem  structures are added or removed from Tcl's internal list of
       known filesystems.

	      typedef int Tcl_FSPathInFilesystemProc(
		      Tcl_Obj *pathPtr,
		      ClientData *clientDataPtr);

   DUPINTERNALREPPROC
       This function makes a copy of a path's internal representation, and  is
       called when Tcl needs to duplicate a path value. If NULL, Tcl will sim‐
       ply not copy the internal representation, which may then need to be re‐
       generated later.

	      typedef ClientData Tcl_FSDupInternalRepProc(
		      ClientData clientData);

   FREEINTERNALREPPROC
       Free  the internal representation. This must be implemented if internal
       representations need freeing (i.e. if some memory is allocated when  an
       internal representation is generated), but may otherwise be NULL.

	      typedef void Tcl_FSFreeInternalRepProc(
		      ClientData clientData);

   INTERNALTONORMALIZEDPROC
       Function	 to convert internal representation to a normalized path. Only
       required if the filesystem creates pure path values with no string/path
       representation.	The return value is a Tcl value whose string represen‐
       tation is the normalized path.

	      typedef Tcl_Obj *Tcl_FSInternalToNormalizedProc(
		      ClientData clientData);

   CREATEINTERNALREPPROC
       Function to take a path value, and calculate an internal representation
       for  it, and store that native representation in the value. May be NULL
       if paths have no	 internal  representation,  or	if  the	 Tcl_FSPathIn‐
       FilesystemProc for this filesystem always immediately creates an inter‐
       nal representation for paths it accepts.

	      typedef ClientData Tcl_FSCreateInternalRepProc(
		      Tcl_Obj *pathPtr);

   NORMALIZEPATHPROC
       Function to normalize a path. Should be implemented for all filesystems
       which can have multiple string representations for the same path value.
       In Tcl, every “path” must have a single unique “normalized” string rep‐
       resentation.  Depending	on  the filesystem, there may be more than one
       unnormalized string representation which refers to  that	 path  (e.g. a
       relative	 path,	a path with different character case if the filesystem
       is case insensitive, a path contain a reference	to  a  home  directory
       such  as	 “~”, a path containing symbolic links, etc). If the very last
       component in the path is a symbolic link, it should  not	 be  converted
       into  the  value	 it points to (but its case or other aspects should be
       made unique). All other path components should be converted  from  sym‐
       bolic  links. This one exception is required to agree with Tcl's seman‐
       tics with file delete, file rename, file	 copy  operating  on  symbolic
       links.	This  function may be called with nextCheckpoint either at the
       beginning of the path (i.e. zero), at the end of the path,  or  at  any
       intermediate  file  separator  in  the path. It will never point to any
       other arbitrary position in the path. In the last of  the  three	 valid
       cases,  the implementation can assume that the path up to and including
       the file separator is known and normalized.

	      typedef int Tcl_FSNormalizePathProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      int nextCheckpoint);

FILESYSTEM OPERATIONS
       The fields in this section of the structure contain addresses of	 func‐
       tions  which are called to carry out the basic filesystem operations. A
       filesystem which expects to be used with the complete standard Tcl com‐
       mand  set  must	implement all of these. If some of them are not imple‐
       mented, then certain Tcl commands may  fail  when  operating  on	 paths
       within  that  filesystem. However, in some instances this may be desir‐
       able (for example, a read-only filesystem should not implement the last
       four  functions, and a filesystem which does not support symbolic links
       need not implement the readlink function, etc.  The  Tcl	 core  expects
       filesystems to behave in this way).

   FILESYSTEMPATHTYPEPROC
       Function	 to  determine	the  type of a path in this filesystem. May be
       NULL, in which case no type information will be available to  users  of
       the filesystem. The “type” is used only for informational purposes, and
       should be returned as the string representation of the Tcl_Obj which is
       returned.  A typical return value might be “networked”, “zip” or “ftp”.
       The Tcl_Obj result is owned by the filesystem and so Tcl will increment
       the reference count of that value if it wishes to retain a reference to
       it.

	      typedef Tcl_Obj *Tcl_FSFilesystemPathTypeProc(
		      Tcl_Obj *pathPtr);

   FILESYSTEMSEPARATORPROC
       Function to return the  separator  character(s)	for  this  filesystem.
       This need only be implemented if the filesystem wishes to use a differ‐
       ent separator than the standard string “/”.  Amongst other uses, it  is
       returned	 by  the  file separator command. The return value should be a
       value with reference count of zero.

	      typedef Tcl_Obj *Tcl_FSFilesystemSeparatorProc(
		      Tcl_Obj *pathPtr);

   STATPROC
       Function to process a Tcl_FSStat call. Must be implemented for any rea‐
       sonable filesystem, since many Tcl level commands depend crucially upon
       it (e.g. file atime, file isdirectory, file size, glob).

	      typedef int Tcl_FSStatProc(
		      Tcl_Obj *pathPtr,
		      Tcl_StatBuf *statPtr);

       The Tcl_FSStatProc fills the stat structure  statPtr  with  information
       about the specified file. You do not need any access rights to the file
       to get this information but you need search rights to  all  directories
       named in the path leading to the file. The stat structure includes info
       regarding device, inode (always 0 on Windows),  privilege  mode,	 nlink
       (always	1 on Windows), user id (always 0 on Windows), group id (always
       0 on Windows), rdev (same as device  on	Windows),  size,  last	access
       time, last modification time, and last metadata change time.

       If the file represented by pathPtr exists, the Tcl_FSStatProc returns 0
       and the stat structure is filled with data. Otherwise, -1 is  returned,
       and no stat info is given.

   ACCESSPROC
       Function	 to  process  a Tcl_FSAccess call. Must be implemented for any
       reasonable filesystem, since many Tcl level commands  depend  crucially
       upon it (e.g. file exists, file readable).

	      typedef int Tcl_FSAccessProc(
		      Tcl_Obj *pathPtr,
		      int mode);

       The  Tcl_FSAccessProc  checks  whether  the process would be allowed to
       read, write or test for existence of the file (or other filesystem  ob‐
       ject)  whose  name  is in pathPtr. If the pathname refers to a symbolic
       link, then the permissions of the file referred by this	symbolic  link
       should be tested.

       On  success  (all  requested permissions granted), zero is returned. On
       error (at least one bit in mode asked for a permission that is  denied,
       or some other  error occurred), -1 is returned.

   OPENFILECHANNELPROC
       Function	 to  process a Tcl_FSOpenFileChannel call. Must be implemented
       for any reasonable filesystem, since any operations which require  open
       or  accessing  a	 file's contents will use it (e.g. open, encoding, and
       many Tk commands).

	      typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      int mode,
		      int permissions);

       The Tcl_FSOpenFileChannelProc opens a file specified by pathPtr and re‐
       turns  a channel handle that can be used to perform input and output on
       the file. This API is modeled after the fopen  procedure	 of  the  Unix
       standard	 I/O library. The syntax and meaning of all arguments is simi‐
       lar to those given in the Tcl open command when opening a  file,	 where
       the  mode  argument  is	a  combination	of  the	 POSIX flags O_RDONLY,
       O_WRONLY, etc. If an  error  occurs  while  opening  the	 channel,  the
       Tcl_FSOpenFileChannelProc  returns  NULL and records a POSIX error code
       that can be retrieved with Tcl_GetErrno.	 In  addition,	if  interp  is
       non-NULL,  the Tcl_FSOpenFileChannelProc leaves an error message in in‐
       terp's result after any error.

       The newly created channel must not be registered in the supplied inter‐
       preter by a Tcl_FSOpenFileChannelProc; that task is up to the caller of
       Tcl_FSOpenFileChannel (if necessary). If one of the standard  channels,
       stdin,  stdout or stderr was previously closed, the act of creating the
       new channel also assigns it as a replacement for the standard channel.

   MATCHINDIRECTORYPROC
       Function to process a Tcl_FSMatchInDirectory call. If not  implemented,
       then  glob  and	recursive  copy	 functionality	will be lacking in the
       filesystem (and this may impact commands like encoding names which  use
       glob functionality internally).

	      typedef int Tcl_FSMatchInDirectoryProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *resultPtr,
		      Tcl_Obj *pathPtr,
		      const char *pattern,
		      Tcl_GlobTypeData *types);

       The  function should return all files or directories (or other filesys‐
       tem objects) which match the given pattern and accord  with  the	 types
       specification  given.  There are two ways in which this function may be
       called. If pattern is NULL, then pathPtr is a full  path	 specification
       of a single file or directory which should be checked for existence and
       correct type. Otherwise, pathPtr is a directory, the contents of	 which
       the function should search for files or directories which have the cor‐
       rect type. In either case, pathPtr can be assumed to be	both  non-NULL
       and non-empty. It is not currently documented whether pathPtr will have
       a file separator at its end of not, so code should be flexible to  both
       possibilities.

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the matching process. Error messages are placed in  interp,
       unless interp in NULL in which case no error message need be generated;
       on a TCL_OK result, results should be  added  to	 the  resultPtr	 value
       given  (which  can  be  assumed	to  be a valid unshared Tcl list). The
       matches added to resultPtr should include  any  path  prefix  given  in
       pathPtr (this usually means they will be absolute path specifications).
       Note that if no matches are found, that simply leads to	an  empty  re‐
       sult;  errors  are only signaled for actual file or filesystem problems
       which may occur during the matching process.

       The Tcl_GlobTypeData structure passed in the types  parameter  contains
       the following fields:

	      typedef struct Tcl_GlobTypeData {
		  /* Corresponds to bcdpfls as in 'find -t' */
		  int type;
		  /* Corresponds to file permissions */
		  int perm;
		  /* Acceptable mac type */
		  Tcl_Obj *macType;
		  /* Acceptable mac creator */
		  Tcl_Obj *macCreator;
	      } Tcl_GlobTypeData;

       There are two specific cases which it is important to handle correctly,
       both when types is non-NULL. The two  cases  are	 when  types->types  &
       TCL_GLOB_TYPE_DIR  or  types->types & TCL_GLOB_TYPE_MOUNT are true (and
       in particular when the other flags are false). In the  first  of	 these
       cases,  the function must list the contained directories. Tcl uses this
       to implement recursive globbing, so it is critical that filesystems im‐
       plement	directory  matching  correctly.	 In the second of these cases,
       with TCL_GLOB_TYPE_MOUNT, the filesystem must  list  the	 mount	points
       which  lie within the given pathPtr (and in this case, pathPtr need not
       lie within the same filesystem - different to all other cases in	 which
       this  function  is  called).  Support for this is critical if Tcl is to
       have seamless transitions between from one filesystem to another.

   UTIMEPROC
       Function to process a Tcl_FSUtime call. Required to allow setting  (not
       reading)	 of  times  with  file	mtime, file atime and the open-r/open-
       w/fcopy implementation of file copy.

	      typedef int Tcl_FSUtimeProc(
		      Tcl_Obj *pathPtr,
		      struct utimbuf *tval);

       The access and modification times of  the  file	specified  by  pathPtr
       should be changed to the values given in the tval structure.

       The return value should be 0 on success and -1 on an error, as with the
       system utime.

   LINKPROC
       Function to process a Tcl_FSLink call. Should be	 implemented  only  if
       the filesystem supports links, and may otherwise be NULL.

	      typedef Tcl_Obj *Tcl_FSLinkProc(
		      Tcl_Obj *linkNamePtr,
		      Tcl_Obj *toPtr,
		      int linkAction);

       If toPtr is NULL, the function is being asked to read the contents of a
       link. The result is a Tcl_Obj specifying the contents of the link given
       by  linkNamePtr,	 or  NULL if the link could not be read. The result is
       owned by the caller (and should therefore have  its  ref	 count	incre‐
       mented before being returned). Any callers should call Tcl_DecrRefCount
       on this result when it is no longer needed.  If toPtr is not NULL,  the
       function	 should	 attempt  to  create  a link.  The result in this case
       should be toPtr if the link was successful and NULL otherwise. In  this
       case the result is not owned by the caller (i.e. no reference count ma‐
       nipulations on either  end  are	needed).  See  the  documentation  for
       Tcl_FSLink for the correct interpretation of the linkAction flags.

   LISTVOLUMESPROC
       Function	 to  list  any	filesystem  volumes  added by this filesystem.
       Should be implemented only if the filesystem adds volumes at  the  head
       of the filesystem, so that they can be returned by file volumes.

	      typedef Tcl_Obj *Tcl_FSListVolumesProc(void);

       The  result  should  be	a list of volumes added by this filesystem, or
       NULL (or an empty list) if no volumes are provided. The result value is
       considered  to  be  owned  by  the  filesystem (not by Tcl's core), but
       should be given a reference count for Tcl. Tcl will use the contents of
       the  list and then decrement that reference count. This allows filesys‐
       tems to choose whether they actually want to retain a “global list”  of
       volumes	or  not (if not, they generate the list on the fly and pass it
       to Tcl with a reference count of 1 and then forget about the  list,  if
       yes,  then  they	 simply	 increment the reference count of their global
       list and pass it to Tcl which will copy the contents and then decrement
       the count back to where it was).

       Therefore, Tcl considers return values from this proc to be read-only.

   FILEATTRSTRINGSPROC
       Function	 to  list  all	attribute  strings  which  are	valid for this
       filesystem. If not implemented the filesystem will not support the file
       attributes  command. This allows arbitrary additional information to be
       attached to files in the filesystem. If it is not implemented, there is
       no need to implement the get and set methods.

	      typedef const char *const *Tcl_FSFileAttrStringsProc(
		      Tcl_Obj *pathPtr,
		      Tcl_Obj **objPtrRef);

       The  called  function may either return an array of strings, or may in‐
       stead return NULL and place a Tcl list into the	given  objPtrRef.  Tcl
       will  take that list and first increment its reference count before us‐
       ing it.	On completion of that use, Tcl will  decrement	its  reference
       count.  Hence  if  the  list should be disposed of by Tcl when done, it
       should have a reference count of zero, and if the list  should  not  be
       disposed	 of,  the  filesystem  should ensure it returns a value with a
       reference count of at least one.

   FILEATTRSGETPROC
       Function to process a Tcl_FSFileAttrsGet call, used by file attributes.

	      typedef int Tcl_FSFileAttrsGetProc(
		      Tcl_Interp *interp,
		      int index,
		      Tcl_Obj *pathPtr,
		      Tcl_Obj **objPtrRef);

       Returns a standard Tcl return  code.  The  attribute  value  retrieved,
       which  corresponds  to the index'th element in the list returned by the
       Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if	TCL_OK
       was  returned)  and is likely to have a reference count of zero. Either
       way we must  either  store  it  somewhere  (e.g. the  Tcl  result),  or
       Incr/Decr its reference count to ensure it is properly freed.

   FILEATTRSSETPROC
       Function to process a Tcl_FSFileAttrsSet call, used by file attributes.
       If the filesystem is read-only, there is no need to implement this.

	      typedef int Tcl_FSFileAttrsSetProc(
		      Tcl_Interp *interp,
		      int index,
		      Tcl_Obj *pathPtr,
		      Tcl_Obj *objPtr);

       The attribute value of the index'th element in the list returned by the
       Tcl_FSFileAttrStringsProc should be set to the objPtr given.

   CREATEDIRECTORYPROC
       Function to process a Tcl_FSCreateDirectory call. Should be implemented
       unless the FS is read-only.

	      typedef int Tcl_FSCreateDirectoryProc(
		      Tcl_Obj *pathPtr);

       The return value is a standard Tcl result indicating whether  an	 error
       occurred	 in  the  process.  If successful, a new directory should have
       been added to the filesystem in the location specified by pathPtr.

   REMOVEDIRECTORYPROC
       Function to process a Tcl_FSRemoveDirectory call. Should be implemented
       unless the FS is read-only.

	      typedef int Tcl_FSRemoveDirectoryProc(
		      Tcl_Obj *pathPtr,
		      int recursive,
		      Tcl_Obj **errorPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the process. If  successful,	 the  directory	 specified  by
       pathPtr	should have been removed from the filesystem. If the recursive
       flag is given, then a non-empty directory should be deleted without er‐
       ror.  If	 this flag is not given, then and the directory is non-empty a
       POSIX “EEXIST” error should be signaled. If an error  does  occur,  the
       name  of	 the file or directory which caused the error should be placed
       in errorPtr.

   DELETEFILEPROC
       Function to process a Tcl_FSDeleteFile call. Should be implemented  un‐
       less the FS is read-only.

	      typedef int Tcl_FSDeleteFileProc(
		      Tcl_Obj *pathPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the process. If successful, the file specified  by  pathPtr
       should  have  been  removed  from  the  filesystem.  Note  that, if the
       filesystem supports symbolic links, Tcl will always call this  function
       and  not	 Tcl_FSRemoveDirectoryProc when needed to delete them (even if
       they are symbolic links to directories).

FILESYSTEM EFFICIENCY
       These functions need not be implemented for a particular filesystem be‐
       cause  the core has a fallback implementation available. See each indi‐
       vidual description for the consequences of leaving the field NULL.

   LSTATPROC
       Function to process a Tcl_FSLstat call. If not  implemented,  Tcl  will
       attempt	to  use	 the statProc defined above instead. Therefore it need
       only be implemented if a filesystem can differentiate between stat  and
       lstat calls.

	      typedef int Tcl_FSLstatProc(
		      Tcl_Obj *pathPtr,
		      Tcl_StatBuf *statPtr);

       The  behavior  of  this	function  is  very  similar  to	 that  of  the
       Tcl_FSStatProc defined above, except that if it is applied  to  a  sym‐
       bolic link, it returns information about the link, not about the target
       file.

   COPYFILEPROC
       Function to process a Tcl_FSCopyFile call. If not implemented Tcl  will
       fall  back  on open-r, open-w and fcopy as a copying mechanism.	There‐
       fore it need only be implemented if the filesystem can perform that ac‐
       tion more efficiently.

	      typedef int Tcl_FSCopyFileProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the copying process. Note that, destPathPtr is the name  of
       the  file  which	 should become the copy of srcPathPtr. It is never the
       name of a directory into which srcPathPtr  could	 be  copied  (i.e. the
       function is much simpler than the Tcl level file copy subcommand). Note
       that, if the filesystem supports symbolic links, Tcl will  always  call
       this  function and not copyDirectoryProc when needed to copy them (even
       if they are symbolic links to directories). Finally, if the  filesystem
       determines  it  cannot support the file copy action, calling Tcl_SetEr‐
       rno(EXDEV) and returning a non-TCL_OK result will tell Tcl to  use  its
       standard fallback mechanisms.

   RENAMEFILEPROC
       Function	 to  process  a Tcl_FSRenameFile call. If not implemented, Tcl
       will fall back on a copy and delete mechanism. Therefore it  need  only
       be  implemented	if  the	 filesystem can perform that action more effi‐
       ciently.

	      typedef int Tcl_FSRenameFileProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr);

       The return value is a standard Tcl result indicating whether  an	 error
       occurred	 in the renaming process. If the filesystem determines it can‐
       not support the file rename action, calling Tcl_SetErrno(EXDEV) and re‐
       turning	a non-TCL_OK result will tell Tcl to use its standard fallback
       mechanisms.

   COPYDIRECTORYPROC
       Function to process a Tcl_FSCopyDirectory call. If not implemented, Tcl
       will  fall  back on a recursive file mkdir, file copy mechanism. There‐
       fore it need only be implemented if the filesystem can perform that ac‐
       tion more efficiently.

	      typedef int Tcl_FSCopyDirectoryProc(
		      Tcl_Obj *srcPathPtr,
		      Tcl_Obj *destPathPtr,
		      Tcl_Obj **errorPtr);

       The  return  value is a standard Tcl result indicating whether an error
       occurred in the copying process. If an error does occur,	 the  name  of
       the  file  or  directory which caused the error should be placed in er‐
       rorPtr. Note that, destPathPtr is the name of the directory-name	 which
       should  become  the mirror-image of srcPathPtr. It is not the name of a
       directory into which srcPathPtr should be copied (i.e. the function  is
       much  simpler than the Tcl level file copy subcommand). Finally, if the
       filesystem determines it cannot	support	 the  directory	 copy  action,
       calling Tcl_SetErrno(EXDEV) and returning a non-TCL_OK result will tell
       Tcl to use its standard fallback mechanisms.

   LOADFILEPROC
       Function to process a Tcl_FSLoadFile call. If not implemented, Tcl will
       fall back on a copy to native-temp followed by a Tcl_FSLoadFile on that
       temporary copy. Therefore it need only be implemented if the filesystem
       can  load  code	directly,  or  it  can be implemented simply to return
       TCL_ERROR to disable load functionality in this filesystem entirely.

	      typedef int Tcl_FSLoadFileProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *pathPtr,
		      Tcl_LoadHandle *handlePtr,
		      Tcl_FSUnloadFileProc *unloadProcPtr);

       Returns a standard Tcl completion code. If an error  occurs,  an	 error
       message	is left in the interp's result. The function dynamically loads
       a binary code file into memory. On a  successful	 load,	the  handlePtr
       should  be filled with a token for the dynamically loaded file, and the
       unloadProcPtr should be filled in with the address of a procedure.  The
       unload  procedure  will	be called with the given Tcl_LoadHandle as its
       only parameter when Tcl needs to unload the file. For example, for  the
       native  filesystem,  the	 Tcl_LoadHandle	 returned is currently a token
       which can be used in the private TclpFindSymbol to access functions  in
       the  new	 code. Each filesystem is free to define the Tcl_LoadHandle as
       it requires. Finally, if the filesystem determines  it  cannot  support
       the  file load action, calling Tcl_SetErrno(EXDEV) and returning a non-
       TCL_OK result will tell Tcl to use its standard fallback mechanisms.

   UNLOADFILEPROC
       Function to unload a previously successfully loaded file. If  load  was
       implemented,  then  this	 should	 also  be implemented, if there is any
       cleanup action required.

	      typedef void Tcl_FSUnloadFileProc(
		      Tcl_LoadHandle loadHandle);

   GETCWDPROC
       Function to process a Tcl_FSGetCwd call. Most filesystems need not  im‐
       plement	this. It will usually only be called once, if getcwd is called
       before chdir. May be NULL.

	      typedef Tcl_Obj *Tcl_FSGetCwdProc(
		      Tcl_Interp *interp);

       If the filesystem supports a native notion of a current working	direc‐
       tory  (which  might  perhaps  change independent of Tcl), this function
       should return that cwd as the result, or NULL if the current  directory
       could  not  be determined (e.g. the user does not have appropriate per‐
       missions on the cwd directory). If NULL is returned, an	error  message
       is left in the interp's result.

   CHDIRPROC
       Function to process a Tcl_FSChdir call. If filesystems do not implement
       this, it will be emulated by a series of directory access checks.  Oth‐
       erwise,	virtual	 filesystems  which  do implement it need only respond
       with a positive return result if the pathPtr is a valid, accessible di‐
       rectory	in  their filesystem. They need not remember the result, since
       that will be automatically remembered for use  by  Tcl_FSGetCwd.	  Real
       filesystems  should carry out the correct action (i.e. call the correct
       system chdir API).

	      typedef int Tcl_FSChdirProc(
		      Tcl_Obj *pathPtr);

       The Tcl_FSChdirProc changes the applications current working  directory
       to  the value specified in pathPtr. The function returns -1 on error or
       0 on success.

SEE ALSO
       cd(n), file(n), filename(n), load(n), open(n), pwd(n),  source(n),  un‐
       load(n)

KEYWORDS
       stat, access, filesystem, vfs, virtual filesystem



Tcl				      8.4			 Filesystem(3)

Tcl_SplitList(3)	    Tcl Library Procedures	      Tcl_SplitList(3)



______________________________________________________________________________

NAME
       Tcl_SplitList,	 Tcl_Merge,    Tcl_ScanElement,	   Tcl_ConvertElement,
       Tcl_ScanCountedElement,	Tcl_ConvertCountedElement  -  manipulate   Tcl
       lists

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_SplitList(interp, list, argcPtr, argvPtr)

       char *
       Tcl_Merge(argc, argv)

       int
       Tcl_ScanElement(src, flagsPtr)

       int
       Tcl_ScanCountedElement(src, length, flagsPtr)

       int
       Tcl_ConvertElement(src, dst, flags)

       int
       Tcl_ConvertCountedElement(src, length, dst, flags)

ARGUMENTS
       Tcl_Interp *interp (out)			  Interpreter to use for error
						  reporting.  If NULL, then no
						  error message is left.

       const char *list (in)			  Pointer  to  a  string  with
						  proper list structure.

       int *argcPtr (out)			  Filled in with number of el‐
						  ements in list.

       const char ***argvPtr (out)		  *argvPtr  will  be filled in
						  with the address of an array
						  of  pointers	to the strings
						  that are the extracted  ele‐
						  ments	 of  list.  There will
						  be *argcPtr valid entries in
						  the  array,  followed	 by  a
						  NULL entry.

       int argc (in)				  Number of elements in argv.

       const char *const *argv (in)		  Array of  strings  to	 merge
						  together into a single list.
						  Each string  will  become  a
						  separate   element   of  the
						  list.

       const char *src (in)			  String that is to become  an
						  element of a list.

       int *flagsPtr (in)			  Pointer  to  word to fill in
						  with information about  src.
						  The  value of *flagsPtr must
						  be passed to Tcl_ConvertEle‐
						  ment.

       int length (in)				  Number  of  bytes  in string
						  src.

       char *dst (in)				  Place to copy converted list
						  element.     Must    contain
						  enough  characters  to  hold
						  converted string.

       int flags (in)				  Information  about src. Must
						  be value returned by	previ‐
						  ous call to Tcl_ScanElement,
						  possibly     OR-ed	  with
						  TCL_DONT_USE_BRACES.
______________________________________________________________________________

DESCRIPTION
       These  procedures  may be used to disassemble and reassemble Tcl lists.
       Tcl_SplitList breaks a list up into its constituent elements, returning
       an  array of pointers to the elements using argcPtr and argvPtr.	 While
       extracting the arguments, Tcl_SplitList obeys the usual rules for back‐
       slash  substitutions  and  braces.   The	 area  of memory pointed to by
       *argvPtr is dynamically allocated;  in addition to the array of	point‐
       ers, it also holds copies of all the list elements.  It is the caller's
       responsibility to free up all of this storage.	For  example,  suppose
       that you have called Tcl_SplitList with the following code:

	      int argc, code;
	      char *string;
	      char **argv;
	      ...
	      code = Tcl_SplitList(interp, string, &argc, &argv);

       Then  you  should eventually free the storage with a call like the fol‐
       lowing:

	      Tcl_Free((char *) argv);

       Tcl_SplitList normally returns TCL_OK, which means the  list  was  suc‐
       cessfully  parsed.  If there was a syntax error in list, then TCL_ERROR
       is returned and the interpreter's result will point to an error message
       describing  the	problem (if interp was not NULL).  If TCL_ERROR is re‐
       turned then no memory is allocated and *argvPtr is not modified.

       Tcl_Merge is the inverse of Tcl_SplitList:  it takes  a	collection  of
       strings	given  by argc and argv and generates a result string that has
       proper list structure.  This means that commands like index may be used
       to  extract the original elements again.	 In addition, if the result of
       Tcl_Merge is passed to Tcl_Eval, it will	 be  parsed  into  argc	 words
       whose  values will be the same as the argv strings passed to Tcl_Merge.
       Tcl_Merge will modify the list elements with braces and/or  backslashes
       in  order  to  produce proper Tcl list structure.  The result string is
       dynamically allocated using Tcl_Alloc;  the caller must eventually  re‐
       lease the space using Tcl_Free.

       If the result of Tcl_Merge is passed to Tcl_SplitList, the elements re‐
       turned  by  Tcl_SplitList  will	be  identical  to  those  passed  into
       Tcl_Merge.   However,  the  converse  is not true:  if Tcl_SplitList is
       passed a given string, and the resulting argc and argv  are  passed  to
       Tcl_Merge,  the	resulting  string  may not be the same as the original
       string passed to Tcl_SplitList.	This  is  because  Tcl_Merge  may  use
       backslashes and braces differently than the original string.

       Tcl_ScanElement	and  Tcl_ConvertElement are the procedures that do all
       of the real work of Tcl_Merge.  Tcl_ScanElement scans its src  argument
       and  determines how to use backslashes and braces when converting it to
       a list element.	It returns an overestimate of the number of characters
       required	 to represent src as a list element, and it stores information
       in *flagsPtr that is needed by Tcl_ConvertElement.

       Tcl_ConvertElement is a companion  procedure  to	 Tcl_ScanElement.   It
       does  the  actual  work	of converting a string to a list element.  Its
       flags argument must be the same as the value returned  by  Tcl_ScanEle‐
       ment.  Tcl_ConvertElement writes a proper list element to memory start‐
       ing at *dst and returns a count of the total number of characters writ‐
       ten, which will be no more than the result returned by Tcl_ScanElement.
       Tcl_ConvertElement writes out only the actual list element without  any
       leading	or  trailing  spaces: it is up to the caller to include spaces
       between adjacent list elements.

       Tcl_ConvertElement uses one of two different approaches to  handle  the
       special characters in src.  Wherever possible, it handles special char‐
       acters by surrounding the string with  braces.	This  produces	clean-
       looking output, but cannot be used in some situations, such as when src
       contains unmatched braces.   In	these  situations,  Tcl_ConvertElement
       handles	special characters by generating backslash sequences for them.
       The caller may insist on the second approach by OR-ing the  flag	 value
       returned	 by  Tcl_ScanElement  with TCL_DONT_USE_BRACES.	 Although this
       will produce an uglier result, it is useful in some special situations,
       such  as when Tcl_ConvertElement is being used to generate a portion of
       an argument for a Tcl command.  In  this	 case,	surrounding  src  with
       curly braces would cause the command not to be parsed correctly.

       By  default,  Tcl_ConvertElement	 will  use quoting in its output to be
       sure the first character of an element is not the hash character (“#”.)
       This  is to be sure the first element of any list passed to eval is not
       mis-parsed as the beginning of a comment.  When a list element  is  not
       the  first  element of a list, this quoting is not necessary.  When the
       caller can be sure that the element is not the first element of a list,
       it can disable quoting of the leading hash character by OR-ing the flag
       value returned by Tcl_ScanElement with TCL_DONT_QUOTE_HASH.

       Tcl_ScanCountedElement and Tcl_ConvertCountedElement are	 the  same  as
       Tcl_ScanElement and Tcl_ConvertElement, except the length of string src
       is specified by the length argument, and the string may contain	embed‐
       ded nulls.

SEE ALSO
       Tcl_ListObjGetElements(3)

KEYWORDS
       backslash, convert, element, list, merge, split, strings



Tcl				      8.0		      Tcl_SplitList(3)

Tcl_SignalId(3)		    Tcl Library Procedures	       Tcl_SignalId(3)



______________________________________________________________________________

NAME
       Tcl_SignalId, Tcl_SignalMsg - Convert signal codes

SYNOPSIS
       #include <tcl.h>

       const char *
       Tcl_SignalId(sig)

       const char *
       Tcl_SignalMsg(sig)


ARGUMENTS
       int sig (in)	     A POSIX signal number such as SIGPIPE.
______________________________________________________________________________


DESCRIPTION
       Tcl_SignalId  and  Tcl_SignalMsg	 return a string representation of the
       provided signal number (sig).  Tcl_SignalId returns a  machine-readable
       textual	identifier  such as “SIGPIPE”.	Tcl_SignalMsg returns a human-
       readable string such as “bus error”.  The  strings  returned  by	 these
       functions are statically allocated and the caller must not free or mod‐
       ify them.


KEYWORDS
       signals, signal numbers



Tcl				      8.3		       Tcl_SignalId(3)

Tcl_ListObj(3)		    Tcl Library Procedures		Tcl_ListObj(3)



______________________________________________________________________________

NAME
       Tcl_ListObjAppendList,	  Tcl_ListObjAppendElement,    Tcl_NewListObj,
       Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength,  Tcl_ListOb‐
       jIndex, Tcl_ListObjReplace - manipulate Tcl values as lists

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_ListObjAppendList(interp, listPtr, elemListPtr)

       int
       Tcl_ListObjAppendElement(interp, listPtr, objPtr)

       Tcl_Obj *
       Tcl_NewListObj(objc, objv)

       Tcl_SetListObj(objPtr, objc, objv)

       int
       Tcl_ListObjGetElements(interp, listPtr, objcPtr, objvPtr)

       int
       Tcl_ListObjLength(interp, listPtr, lengthPtr)

       int
       Tcl_ListObjIndex(interp, listPtr, index, objPtrPtr)

       int
       Tcl_ListObjReplace(interp, listPtr, first, count, objc, objv)

ARGUMENTS
       Tcl_Interp *interp (in)			 If an error occurs while con‐
						 verting a value to be a  list
						 value,	 an  error  message is
						 left in the interpreter's re‐
						 sult  value  unless interp is
						 NULL.

       Tcl_Obj *listPtr (in/out)		 Points to the list  value  to
						 be  manipulated.   If listPtr
						 does not already point	 to  a
						 list  value,  an attempt will
						 be made to convert it to one.

       Tcl_Obj *elemListPtr (in/out)		 For	Tcl_ListObjAppendList,
						 this  points  to a list value
						 containing elements to be ap‐
						 pended	 onto  listPtr.	  Each
						 element of *elemListPtr  will
						 become	  a   new  element  of
						 listPtr.  If *elemListPtr  is
						 not NULL and does not already
						 point to a list value, an at‐
						 tempt will be made to convert
						 it to one.

       Tcl_Obj *objPtr (in)			 For Tcl_ListObjAppendElement,
						 points	 to the Tcl value that
						 will be appended to  listPtr.
						 For	Tcl_SetListObj,	  this
						 points to the Tcl value  that
						 will  be  converted to a list
						 value containing the objc el‐
						 ements	 of  the  array refer‐
						 enced by objv.

       int *objcPtr (in)			 Points	 to   location	 where
						 Tcl_ListObjGetElements stores
						 the number of element	values
						 in listPtr.

       Tcl_Obj ***objvPtr (out)			 A  location where Tcl_ListOb‐
						 jGetElements stores a pointer
						 to  an	 array	of pointers to
						 the   element	  values    of
						 listPtr.

       int objc (in)				 The number of Tcl values that
						 Tcl_NewListObj	 will	insert
						 into  a  new  list value, and
						 Tcl_ListObjReplace  will  in‐
						 sert	into   listPtr.	   For
						 Tcl_SetListObj, the number of
						 Tcl values to insert into ob‐
						 jPtr.

       Tcl_Obj *const objv[] (in)		 An array of pointers to  val‐
						 ues.  Tcl_NewListObj will in‐
						 sert these values into a  new
						 list value and Tcl_ListObjRe‐
						 place will insert  them  into
						 an  existing  listPtr.	  Each
						 value will become a  separate
						 list element.

       int *lengthPtr (out)			 Points	  to   location	 where
						 Tcl_ListObjLength stores  the
						 length of the list.

       int index (in)				 Index	of  the	 list  element
						 that Tcl_ListObjIndex	is  to
						 return.   The	first  element
						 has index 0.

       Tcl_Obj **objPtrPtr (out)		 Points	  to	place	 where
						 Tcl_ListObjIndex  is to store
						 a pointer  to	the  resulting
						 list element value.

       int first (in)				 Index	of  the	 starting list
						 element  that	Tcl_ListObjRe‐
						 place	is  to	replace.   The
						 list's first element has  in‐
						 dex 0.

       int count (in)				 The  number  of elements that
						 Tcl_ListObjReplace is to  re‐
						 place.
______________________________________________________________________________


DESCRIPTION
       Tcl list values have an internal representation that supports the effi‐
       cient indexing and appending.  The procedures  described	 in  this  man
       page  are  used to create, modify, index, and append to Tcl list values
       from C code.

       Tcl_ListObjAppendList and Tcl_ListObjAppendElement both add one or more
       values to the end of the list value referenced by listPtr.  Tcl_ListOb‐
       jAppendList appends each element of the list value referenced by	 elem‐
       ListPtr	while Tcl_ListObjAppendElement appends the single value refer‐
       enced by objPtr.	 Both procedures will convert the value referenced  by
       listPtr	to  a list value if necessary.	If an error occurs during con‐
       version, both procedures return TCL_ERROR and leave an error message in
       the  interpreter's  result  value if interp is not NULL.	 Similarly, if
       elemListPtr does not already refer  to  a  list	value,	Tcl_ListObjAp‐
       pendList	 will attempt to convert it to one and if an error occurs dur‐
       ing conversion, will return TCL_ERROR and leave an error message in the
       interpreter's  result value if interp is not NULL.  Both procedures in‐
       validate any old string representation of listPtr and, if it  was  con‐
       verted  to  a  list value, free any old internal representation.	 Simi‐
       larly, Tcl_ListObjAppendList frees any old internal  representation  of
       elemListPtr  if	it  converts it to a list value.  After appending each
       element in elemListPtr, Tcl_ListObjAppendList increments the  element's
       reference count since listPtr now also refers to it.  For the same rea‐
       son, Tcl_ListObjAppendElement increments objPtr's reference count.   If
       no  error  occurs, the two procedures return TCL_OK after appending the
       values.

       Tcl_NewListObj and Tcl_SetListObj create a new value or modify  an  ex‐
       isting  value to hold the objc elements of the array referenced by objv
       where each element is a pointer to a Tcl value.	If objc is  less  than
       or  equal to zero, they return an empty value. If objv is NULL, the re‐
       sulting list contains 0 elements, with reserved space  in  an  internal
       representation  for  objc  more	elements  (to  avoid  its reallocation
       later).	The new value's string representation is  left	invalid.   The
       two  procedures	increment the reference counts of the elements in objc
       since the list value now refers to them.	 The new list  value  returned
       by Tcl_NewListObj has reference count zero.

       Tcl_ListObjGetElements returns a count and a pointer to an array of the
       elements in a list value.  It returns the count by storing  it  in  the
       address objcPtr.	 Similarly, it returns the array pointer by storing it
       in the address objvPtr.	The memory pointed to is managed  by  Tcl  and
       should  not be freed or written to by the caller. If the list is empty,
       0 is stored at objcPtr and NULL at objvPtr.  If listPtr is not  already
       a list value, Tcl_ListObjGetElements will attempt to convert it to one;
       if the conversion fails, it returns TCL_ERROR and leaves an error  mes‐
       sage  in	 the interpreter's result value if interp is not NULL.	Other‐
       wise it returns TCL_OK after storing the count and array pointer.

       Tcl_ListObjLength returns the number of elements in the list value ref‐
       erenced by listPtr.  It returns this count by storing an integer in the
       address lengthPtr.  If the value is not already a list value,  Tcl_Lis‐
       tObjLength  will attempt to convert it to one; if the conversion fails,
       it returns TCL_ERROR and leaves an error message in  the	 interpreter's
       result  value if interp is not NULL.  Otherwise it returns TCL_OK after
       storing the list's length.

       The procedure Tcl_ListObjIndex returns a pointer to the value  at  ele‐
       ment index in the list referenced by listPtr.  It returns this value by
       storing a pointer to it in the address objPtrPtr.  If listPtr does  not
       already refer to a list value, Tcl_ListObjIndex will attempt to convert
       it to one; if the conversion fails, it returns TCL_ERROR and leaves  an
       error  message in the interpreter's result value if interp is not NULL.
       If the index is out of range, that is, index  is	 negative  or  greater
       than  or	 equal to the number of elements in the list, Tcl_ListObjIndex
       stores a NULL in objPtrPtr and returns TCL_OK.	Otherwise  it  returns
       TCL_OK  after storing the element's value pointer.  The reference count
       for the list element is not incremented; the caller must do that if  it
       needs to retain a pointer to the element.

       Tcl_ListObjReplace  replaces  zero  or more elements of the list refer‐
       enced by listPtr with the objc values in the array referenced by	 objv.
       If  listPtr does not point to a list value, Tcl_ListObjReplace will at‐
       tempt to convert it to one; if the conversion fails, it returns TCL_ER‐
       ROR  and	 leaves	 an error message in the interpreter's result value if
       interp is not NULL.  Otherwise, it returns TCL_OK after	replacing  the
       values.	 If  objv is NULL, no new elements are added.  If the argument
       first is zero or negative, it refers to the first element.  If first is
       greater	than  or  equal to the number of elements in the list, then no
       elements are deleted; the new elements are appended to the list.	 count
       gives  the number of elements to replace.  If count is zero or negative
       then no elements are deleted; the new elements are simply inserted  be‐
       fore  the  one  designated  by  first.	Tcl_ListObjReplace invalidates
       listPtr's old string representation.  The reference counts of any  ele‐
       ments  inserted	from objv are incremented since the resulting list now
       refers to them.	Similarly, the reference counts for any replaced  val‐
       ues are decremented.

       Because	Tcl_ListObjReplace  combines  both element insertion and dele‐
       tion, it can be used to implement a number of list operations.  For ex‐
       ample, the following code inserts the objc values referenced by the ar‐
       ray of value pointers objv just before the element index	 of  the  list
       referenced by listPtr:

	      result = Tcl_ListObjReplace(interp, listPtr, index, 0,
		      objc, objv);

       Similarly, the following code appends the objc values referenced by the
       array objv to the end of the list listPtr:

	      result = Tcl_ListObjLength(interp, listPtr, &length);
	      if (result == TCL_OK) {
		  result = Tcl_ListObjReplace(interp, listPtr, length, 0,
			  objc, objv);
	      }

       The count list elements starting at first  can  be  deleted  by	simply
       calling Tcl_ListObjReplace with a NULL objvPtr:

	      result = Tcl_ListObjReplace(interp, listPtr, first, count,
		      0, NULL);

SEE ALSO
       Tcl_NewObj(3),  Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjRe‐
       sult(3)

KEYWORDS
       append, index, insert,  internal	 representation,  length,  list,  list
       value, list type, value, value type, replace, string representation



Tcl				      8.0			Tcl_ListObj(3)

Tcl_Exit(3)		    Tcl Library Procedures		   Tcl_Exit(3)



______________________________________________________________________________

NAME
       Tcl_Exit,  Tcl_Finalize,	 Tcl_CreateExitHandler, Tcl_DeleteExitHandler,
       Tcl_ExitThread,	  Tcl_FinalizeThread,	  Tcl_CreateThreadExitHandler,
       Tcl_DeleteThreadExitHandler,  Tcl_SetExitProc  - end the application or
       thread (and invoke exit handlers)

SYNOPSIS
       #include <tcl.h>

       Tcl_Exit(status)

       Tcl_Finalize()

       Tcl_CreateExitHandler(proc, clientData)

       Tcl_DeleteExitHandler(proc, clientData)

       Tcl_ExitThread(status)

       Tcl_FinalizeThread()

       Tcl_CreateThreadExitHandler(proc, clientData)

       Tcl_DeleteThreadExitHandler(proc, clientData)

       Tcl_ExitProc *
       Tcl_SetExitProc(proc)

ARGUMENTS
       int status (in)			     Provides  information  about  why
					     the application or thread exited.
					     Exact meaning  may	 be  platform-
					     specific.	0 usually means a nor‐
					     mal exit, any nonzero value  usu‐
					     ally  means  that	an  error  oc‐
					     curred.

       Tcl_ExitProc *proc (in)		     Procedure to invoke before	 exit‐
					     ing  application, or (for Tcl_Se‐
					     tExitProc) NULL to uninstall  the
					     current  application  exit proce‐
					     dure.

       ClientData clientData (in)	     Arbitrary one-word value to  pass
					     to proc.
______________________________________________________________________________


DESCRIPTION
       The  procedures	described here provide a graceful mechanism to end the
       execution of a Tcl application. Exit handlers are  invoked  to  cleanup
       the application's state before ending the execution of Tcl code.

       Invoke Tcl_Exit to end a Tcl application and to exit from this process.
       This procedure is invoked by the exit command, and can be invoked  any‐
       place else to terminate the application.	 No-one should ever invoke the
       exit system procedure directly;	always	invoke	Tcl_Exit  instead,  so
       that it can invoke exit handlers.  Note that if other code invokes exit
       system procedure directly, or otherwise causes the application to  ter‐
       minate  without	calling	 Tcl_Exit,  the exit handlers will not be run.
       Tcl_Exit internally invokes the exit system call, thus it never returns
       control	to  its	 caller.   If an application exit handler has been in‐
       stalled (see Tcl_SetExitProc), that handler is invoked with an argument
       consisting  of  the  exit  status (cast to ClientData); the application
       exit handler should not return control to Tcl.

       Tcl_Finalize is similar to Tcl_Exit except that it does not  exit  from
       the  current  process.	It is useful for cleaning up when a process is
       finished using Tcl but wishes to continue executing, and	 when  Tcl  is
       used  in	 a  dynamically loaded extension that is about to be unloaded.
       Your code should always invoke Tcl_Finalize when Tcl is being unloaded,
       to  ensure  proper cleanup. Tcl_Finalize can be safely called more than
       once.

       Tcl_ExitThread is used to terminate the current thread and invoke  per-
       thread exit handlers.  This finalization is done by Tcl_FinalizeThread,
       which you can call if you just want to clean up	per-thread  state  and
       invoke the thread exit handlers.	 Tcl_Finalize calls Tcl_FinalizeThread
       for the current thread automatically.

       Tcl_CreateExitHandler arranges for proc to be invoked  by  Tcl_Finalize
       and  Tcl_Exit.  Tcl_CreateThreadExitHandler arranges for proc to be in‐
       voked by Tcl_FinalizeThread and Tcl_ExitThread.	This provides  a  hook
       for cleanup operations such as flushing buffers and freeing global mem‐
       ory.  Proc should match the type Tcl_ExitProc:

	      typedef void Tcl_ExitProc(
		      ClientData clientData);

       The clientData parameter to proc is a copy of the  clientData  argument
       given  to Tcl_CreateExitHandler or Tcl_CreateThreadExitHandler when the
       callback was created.  Typically, clientData points to a data structure
       containing application-specific information about what to do in proc.

       Tcl_DeleteExitHandler  and Tcl_DeleteThreadExitHandler may be called to
       delete a previously-created exit handler.  It removes the handler indi‐
       cated  by proc and clientData so that no call to proc will be made.  If
       no such handler exists then Tcl_DeleteExitHandler or  Tcl_DeleteThread‐
       ExitHandler does nothing.

       Tcl_Finalize  and Tcl_Exit execute all registered exit handlers, in re‐
       verse order from the order in which they were registered.  This matches
       the  natural  order in which extensions are loaded and unloaded; if ex‐
       tension A loads extension B, it usually unloads B before it  itself  is
       unloaded.   If  extension  A registers its exit handlers before loading
       extension B, this ensures that any exit handlers for B will be executed
       before the exit handlers for A.

       Tcl_Finalize  and  Tcl_Exit call Tcl_FinalizeThread and the thread exit
       handlers after the process-wide exit handlers.  This is because	thread
       finalization  shuts  down the I/O channel system, so any attempt at I/O
       by the global exit handlers will vanish into the bitbucket.

       Tcl_SetExitProc installs an application	exit  handler,	returning  the
       previously-installed application exit handler or NULL if no application
       handler was installed.  If an application exit  handler	is  installed,
       that  exit  handler takes over complete responsibility for finalization
       of Tcl's subsystems via Tcl_Finalize at an appropriate time.  The argu‐
       ment passed to proc when it is invoked will be the exit status code (as
       passed to Tcl_Exit) cast to a ClientData value.

SEE ALSO
       exit(n)

KEYWORDS
       abort, callback, cleanup, dynamic loading, end application,  exit,  un‐
       loading, thread



Tcl				      8.5			   Tcl_Exit(3)