Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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_FSMatchInDirectory, Tcl_FSLink, Tcl_FSL-
       stat,  Tcl_FSUtime,  Tcl_FSFileAttrsGet,	 Tcl_FSFileAttrsSet,   Tcl_FS-
       FileAttrStrings,	  Tcl_FSStat,	Tcl_FSAccess,	Tcl_FSOpenFileChannel,
       Tcl_FSGetCwd,   Tcl_FSChdir,    Tcl_FSPathSeparator,    Tcl_FSJoinPath,
       Tcl_FSSplitPath,	Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoin-
       ToPath, Tcl_FSConvertToPathType,	Tcl_FSGetInternalRep,  Tcl_FSGetTrans-
       latedPath,  Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FS-
       GetNativePath, Tcl_FSFileSystemInfo, Tcl_AllocStatBuf -	procedures  to
       interact	with any filesystem

SYNOPSIS
       #include	<tcl.h>

       int
       Tcl_FSRegister(clientData, fsPtr)

       int
       Tcl_FSUnregister(fsPtr)

       ClientData
       Tcl_FSData(fsPtr)

       void
       Tcl_FSMountsChanged(fsPtr)

       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, int 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,
		      handlePtr, unloadProcPtr)

       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, int index, pathPtr, objPtrRef)

       int
       Tcl_FSFileAttrsSet(interp, int index, pathPtr, Tcl_Obj *objPtr)

       const char**
       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)

       ClientData
       Tcl_FSGetInternalRep(pathPtr, fsPtr)

       Tcl_Obj *
       Tcl_FSGetTranslatedPath(interp, pathPtr)

       const char *
       Tcl_FSGetTranslatedStringPath(interp, pathPtr)

       Tcl_Obj*
       Tcl_FSNewNativePath(fsPtr, clientData)

       const char *
       Tcl_FSGetNativePath(pathPtr)

       Tcl_Obj*
       Tcl_FSFileSystemInfo(pathPtr)

       Tcl_StatBuf*
       Tcl_AllocStatBuf()

ARGUMENTS
       Tcl_Filesystem *fsPtr (in)			  Points  to  a	struc-
							  ture containing  the
							  addresses  of	proce-
							  dures	 that  can  be
							  called   to  perform
							  the various filesys-
							  tem operations.

       Tcl_Obj *pathPtr	(in)				  The path represented
							  by  this  object  is
							  used	for the	opera-
							  tion	in   question.
							  If  the  object does
							  not already have  an
							  internal path	repre-
							  sentation,  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	desti-
							  nation  filename for
							  a copy or rename op-
							  eration.

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

       const char *pattern (in)				  Only files or	direc-
							  tories matching this
							  pattern  will	be re-
							  turned.

       Tcl_GlobTypeData	*types (in)			  Only files or	direc-
							  tories  matching the
							  type	  descriptions
							  contained   in  this
							  structure  will   be
							  returned.   This pa-
							  rameter may be NULL.

       Tcl_Interp *interp (in)				  Interpreter  to  use
							  either  for results,
							  evaluation,  or  re-
							  porting  error  mes-
							  sages.

       ClientData clientData (in)			  The native  descrip-
							  tion of the path ob-
							  ject to create.

       Tcl_Obj *firstPtr (in)				  The  first  of   two
							  path objects to com-
							  pare.	  The	object
							  may  be converted to
							  path type.

       Tcl_Obj *secondPtr (in)				  The  second  of  two
							  path objects to com-
							  pare.	  The	object
							  may  be converted to
							  path type.

       Tcl_Obj *listObj	(in)				  The list of path el-
							  ements to operate on
							  with a  join	opera-
							  tion.

       int elements (in)				  If non-negative, the
							  number  of  elements
							  in the listObj which
							  should be joined to-
							  gether.    If	 nega-
							  tive,	then all  ele-
							  ments	are joined.

       Tcl_Obj **errorPtr (out)				  In  the  case	 of an
							  error,  filled  with
							  an object containing
							  the name of the file
							  which	 caused	an er-
							  ror in  the  various
							  copy/rename	opera-
							  tions.

       Tcl_Obj **objPtrRef (out)			  Filled with  an  ob-
							  ject	containing the
							  result of the	opera-
							  tion.

       Tcl_Obj *resultPtr (out)				  Pre-allocated	object
							  in  which  to	 store
							  (using   Tcl_ListOb-
							  jAppendElement)  the
							  list of files	or di-
							  rectories 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 ex-
							  ists and  has	 read,
							  write	 and   execute
							  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	table

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

       Tcl_PackageInitProc **proc1Ptr (out)		  Filled with the init
							  function  for	  this
							  code.

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

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

       Tcl_LoadHandle *handlePtr (out)			  Filled  with	an ab-
							  stract token	repre-
							  senting  the	loaded
							  file.

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

       utimbuf *tval (in)				  The access and modi-
							  fication  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 ac-
							  cessed.   May	  have
							  any  of  the	values
							  allowed for the mode
							  argument  to the Tcl
							  open command.

       int permissions (in)				  POSIX-style  permis-
							  sion	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  ele-
							  ments	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  underlying
							  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	function calls
       deal with any "Utf to platform-native" path conversions	which  may  be
       required	(and may cache the results of such conversions for greater ef-
       ficiency	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_FS-
       Register)  may reroute file access to alternative media or access meth-
       ods.  This means	that all of these functions (and therefore the	corre-
       sponding	 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	inter-
       cept 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 pro-
       vide a lookup table of functions	to implement all or some of the	 func-
       tionality  listed  here.	 Finally, the Tcl_FSStat and Tcl_FSLstat calls
       abstract	away from what the "struct stat" buffer	is  actually  declared
       to  be, allowing	the same code to be used both on systems with and sys-
       tems without support for	files larger than 2GB in size.

       The Tcl_FS API is objectified 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  objects  with  a
       reference  count	of zero	to any of these	functions.  If such calls were
       handled,	they might result in memory leaks (under  some	circumstances,
       the filesystem code may wish to retain a	reference to the passed	in ob-
       ject, and so one	must not assume	that after any of these	calls  return,
       the  object  still has a	reference count	of zero	- it may have been in-
       cremented) or in	a direct segmentation fault (or	 other	memory	access
       error)  due  to the object being	freed part way through the complex ob-
       ject 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, objects with a reference	count of zero are considered not to be
       valid filesystem	paths and calling any Tcl_FS API function with such an
       object 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	"\32" (^Z) for |
       all platforms.  If you require a	"^Z" in	code  for  string  comparison, |
       you can use "\032" or "\u001a", which will be safely substituted	by the |
       Tcl interpreter into "^Z".  Tcl_FSEvalFile  is  a  simpler  version  of |
       Tcl_FSEvalFileEx	 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
       belongs	will  be  called.   If that filesystem does not	implement this
       function	(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.

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

       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	ORed  combination  of  TCL_CREATE_SYMBOLIC_LINK	 and  TCL_CRE-
       ATE_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 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 regard-
       ing 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  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 an	object 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 object.

       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  per-
       missions	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 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 regard-
       ing  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 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 object 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	object 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 object, 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	object before  using  it.   In
       particular,  the	returned object	could be an element of the given list,
       so freeing the list might free the object prematurely if	 no  reference
       count  has been taken.  If the number of	elements is zero, then the re-
       turned object 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	object containing each segment of that path as
       an element.  It returns a list object with a reference count  of	 zero.
       If  the passed in lenPtr	is non-NULL, the variable it points to will be
       updated 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 this important  function	 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 object, owned by Tcl,  or	 NULL  if  the
       path was	invalid	or could otherwise not be successfully converted.  Ex-
       traction	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	object
       may be freed any	time the cwd changes) -	the caller can of  course  in-
       crement the refCount if it wishes to maintain a copy for	longer.

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

       Returns object, typically with refCount of zero (but it could be	shared
       under some conditions), containing the joined path.   The  caller  must
       add  a  refCount	 to the	object before using it.	 If any	of the objects
       passed into this	function (pathPtr or path elements) have a refCount of
       zero, they will be freed	when this function returns.

       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  object  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 object 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 object, in the given filesystem.  If the path object 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 object 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 object 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_GetNativePath  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_GetNativePath are usually better functions to  use  for  most  pur-
       poses.

       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 object type.

       The resulting object is a pure "path" object, 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,	and assumes the	native representation is string-based.
       It may be desirable in the future to have non-string-based native  rep-
       resentations (for example, on MacOSX, a representation using a fileSpec
       of FSRef	structure would	probably be more  efficient).	On  Windows  a
       full  Unicode representation would allow	for paths of unlimited length.
       Currently the representation is simply a	 character  string  which  may
       contain	either	the  relative  path or a complete, absolute 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	 abso-
       lute,  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_FSGet-
       TranslatedPath).

       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 sec-
       ond element may be empty	if the filesystem does not provide  a  further
       categorization of files.

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

       Tcl_FSGetFileSystemForPath returns the 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

       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 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	object 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	behaviour 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
       internal	 (filesystem  specific)	representation of the path, which will
       be cached inside	the path object, 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 object.  If	NULL, Tcl will
       simply not copy the internal representation, which may then need	to  be
       regenerated 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  objects   with   no
       string/path  representation.   The  return  value is a Tcl object whose
       string representation is	the normalized path.

	      typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
		      ClientData clientData);

   CREATEINTERNALREPPROC
       Function	to take	a path object, and calculate an	 internal  representa-
       tion  for  it, and store	that native representation in the object.  May
       be NULL if paths	have no	internal representation,  or  if  the  Tcl_FS-
       PathInFilesystemProc  for this filesystem always	immediately creates an
       internal	representation for paths it accepts.

	      typedef ClientData Tcl_FSCreateInternalRepProc(
		      Tcl_Obj *pathPtr);

   NORMALIZEPATHPROC
       Function	to normalize a path.  Should be	implemented for	 all  filesys-
       tems  which  can	have multiple string representations for the same path
       object.	In Tcl,	every "path" must have a  single  unique  "normalized"
       string  representation.	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 object it points to	(but its case or other aspects
       should be made unique).	All other path components should be  converted
       from  symbolic  links.	This  one  exception is	required to agree with
       Tcl's semantics 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 in-
       cluding 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  refCount  of that object 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 an
       object with refCount of zero.

	      typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
		      Tcl_Obj *pathPtr);

   STATPROC
       Function	to process a Tcl_FSStat	call.  Must  be	 implemented  for  any
       reasonable  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 directo-
       ries  named  in	the  path leading to the file.	The stat 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.

       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 registered in	 the  supplied	inter-
       preter; that task is up to the caller of	Tcl_FSOpenFileChannel (if nec-
       essary).	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	object
       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 re-
       sult is owned by	the caller (and	should therefore have  its  ref	 count
       incremented  before being returned).  Any callers should	call Tcl_Decr-
       RefCount	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 ref count ma-
       nipulation on either end	is needed). See	the documentation for  Tcl_FS-
       Link 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	object
       is  considered  to  be owned by the filesystem (not by Tcl's core), but
       should be given a refCount for Tcl.  Tcl	will use the contents  of  the
       list  and  then	decrement  that	 refCount.  This allows	filesystems to
       choose whether they actually want to retain a "master list" of  volumes
       or  not	(if  not, they generate	the list on the	fly and	pass it	to Tcl
       with a refCount of 1 and	then forget about the list, if yes, then  they
       simply  increment  the refCount of their	master 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** 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 an object	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	imple-
       mented 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	imple-
       mented 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_SetErrno(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.
       Therefore it need only be implemented if	 the  filesystem  can  perform
       that action 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  en-
       tirely.

	      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	imple-
       ment  this, it will be emulated by a series of directory	access checks.
       Otherwise, 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), load(n),	open(n), pwd(n), unload(n)

KEYWORDS
       stat, access, filesystem, vfs, virtual

Tcl				      8.4			 Filesystem(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | THE VIRTUAL FILESYSTEM API | FILESYSTEM INFRASTRUCTURE | FILESYSTEM OPERATIONS | FILESYSTEM EFFICIENCY | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_AllocStatBuf.tcl85&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help