Tcl_FSCopyFile man page on OpenServer

Man page or keyword search:  
man Server   5388 pages
apropos Keyword Search (all sections)
Output format
OpenServer logo
[printable version]

Filesystem(3)		    Tcl Library Procedures		 Filesystem(3)

______________________________________________________________________________

NAME
       Tcl_FSRegister,	 Tcl_FSUnregister,   Tcl_FSData,  Tcl_FSMountsChanged,
       Tcl_FSGetFileSystemForPath,     Tcl_FSGetPathType,      Tcl_FSCopyFile,
       Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRe-
       moveDirectory,  Tcl_FSRenameFile,  Tcl_FSListVolumes,   Tcl_FSEvalFile,
       Tcl_FSLoadFile,	  Tcl_FSMatchInDirectory,   Tcl_FSLink,	  Tcl_FSLstat,
       Tcl_FSUtime,  Tcl_FSFileAttrsGet,   Tcl_FSFileAttrsSet,	 Tcl_FSFileAt-
       trStrings,     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_FSGetNativePath, Tcl_FSFileSystemInfo,  Tcl_AllocStatBuf  -	proce-
       dures 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(pathObjPtr)

       Tcl_PathType
       Tcl_FSGetPathType(pathObjPtr)

       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_FSEvalFile(interp, pathPtr)

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

       int
       Tcl_FSMatchInDirectory(interp, result, 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  structure containing
					   the addresses  of  procedures  that
					   can	be called to perform the vari-
					   ous filesystem operations.

       Tcl_Obj		*pathPtr (in)	   The path represented by this object
					   is  used for the operation in ques-
					   tion.   If  the  object  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 filename for a copy  or
					   rename operation.

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

       GlobTypeData	*types	 (in)	   Only	 files or directories matching
					   the type descriptions contained  in
					   this	 structure will be returned by
					   Tcl_FSMatchInDirectory.  It is very
					   important that the 'directory' flag
					   is properly handled.	 This  parame-
					   ter may be NULL.

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

       ClientData	clientData(in)	   The	native description of the path
					   object to create.

       Tcl_Obj		*firstPtr(in)	   The first of two  path  objects  to
					   compare.   The  object  may be con-
					   verted to path type.

       Tcl_Obj		*secondPtr(in)	   The second of two path  objects  to
					   compare.   The  object  may be con-
					   verted to path type.

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

       int		elements (in)	   If non-negative, the number of ele-
					   ments in the listObj	 which	should
					   be  joined  together.  If negative,
					   then all elements 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	 error
					   in  the  various copy/rename opera-
					   tions.

       Tcl_Obj		**objPtrRef(out)   Filled with	an  object  containing
					   the result of the operation.

       Tcl_Obj		*result	 (out)	   Pre-allocated  object  in  which to
					   store (by lappending) the  list  of
					   files or directories which are suc-
					   cessfully	    matched	    in
					   Tcl_FSMatchInDirectory.

       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  execute  permis-
					   sions,  respectively.   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 opera-
					   tion.

       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.

       Tcl_LoadHandle	*handlePtr(out)	   Filled with an abstract token  rep-
					   resenting the loaded file.

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

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

       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 val-
					   ues	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.
_________________________________________________________________

DESCRIPTION
       There are several reasons for calling the  Tcl_FS...  functions	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, MacOS 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 plat-
       form-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 which has been
       registered (through Tcl_FSRegister) may reroute file access to alterna-
       tive  media  or access methods.	This means that all of these functions
       (and therefore 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  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 vfs's 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 buffer is actually
       declared to be, allowing the same code to be used both on systems  with
       and systems without support for files larger than 2GB in size.

       The  Tcl_FS...  are  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
       refCount 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 object,
       and  so	one  must not assume that after any of these calls return, the
       object still has a refCount of zero - it may have been incremented), or
       in a direct segfault due to the object being freed part way through the
       complex object 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_FS...(path) ; Tcl_DecrRefCount(path) is wrong, and may segfault.
       The 'path' must have its refCount incremented before passing it in,  or
       decrementing  it.  For this reason, objects with a refCount of zero are
       considered not to be valid filesystem paths and calling any Tcl_FS  API
       with such an object will result in no action being taken.

       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 Tcl's errno 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	Tcl's  errno  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 Tcl's errno  to  the
       'EXDEV' posix error code (which signifies a ``cross-domain 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 refCount of 0).

       Tcl_FSEvalFile reads the file given by pathPtr and evaluates  its  con-
       tents  as a Tcl script.	It returns the same information as Tcl_EvalOb-
       jEx.  If the file couldn't be read then a  Tcl  error  is  returned  to
       describe why the file couldn't 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_FSLoadFile dynamically loads a binary code  file  into  memory  and
       returns	the  addresses of two procedures within that file, if they are
       defined.	 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,  but  good
       results are placed in the resultPtr given.
			  Note	that the 'glob' code implements recursive pat-
       terns internally, so this function will only ever be passed simple pat-
       terns, which can be matched using the logic of 'string match'.  To han-
       dle recursion, Tcl will call this function frequently asking  only  for
       directories to be returned.

       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 readlink 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'd  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
       should be 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 creation 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.

       For results see 'utime' documentation.	If  successful,	 the  function
       will update the 'atime' and 'mtime' values of the file given.

       Tcl_FSFileAttrsGet  implements  read  access  for  the  hookable	 'file
       attributes' 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
       attributes' 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
       instead return NULL and place a Tcl list into the given objPtrRef.  Tcl
       will take that list and first increment its refCount before  using  it.
       On  completion  of that use, Tcl will decrement its refCount.  Hence if
       the list should be disposed of by Tcl when done, it should have a  ref-
       Count  of zero, and if the list should not be disposed of, the filesys-
       tem should ensure it retains a refCount on the object.

       Tcl_FSAccess checks whether the process would be allowed to read, write
       or  test	 for existence of the file (or other file system 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 creation 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
       error 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, described  below.   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.

       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, in the  case  for
       which the cwd 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 refCount  incremented  for
       the  caller.   When  it	is  no	longer needed, that refCount should be
       decremented.  This is needed for thread-safety purposes, to allow  mul-
       tiple  threads to access this and related functions, while ensuring the
       results are always valid.

       Tcl_FSChdir replaces the library version of chdir().  The path is  nor-
       malized	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
       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 should be a valid list,
       and returns the path object given by considering the  first  'elements'
       elements	 as  valid  path segments.  If elements < 0, we use the entire
       list.

       Returns object with refCount of zero, containing the joined path.

       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.

       Returns list object with refCount of zero.  If the passed in lenPtr  is
       non-NULL,  we  use  it to return 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, with refCount of zero,  or  NULL
       if  the	path  was  invalid or could otherwise not be successfully con-
       verted.	Extraction 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.

       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 with refCount of zero, containing the joined path.

       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 that reverse of the usual
       obj->path->nativerep conversions.  If some code	retrieves  a  path  in
       native  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/MacOS  native  filesys-
       tems,  so  that	they  can easily retrieve the native (char* or TCHAR*)
       representation of a path.   This	 function  is  a  convenience  wrapper
       around  Tcl_FSGetInternalRep,  and assumes the native representation is
       string-based.  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
       unlimited length.  Currently the representation is simply  a  character
       string containing the complete, absolute path in the native encoding.

       The  native  representation  is	cached	so that repeated calls to this
       function will not require additional conversions.

       Tcl_FSFileSystemInfo returns a list of two elements.  The first element
       is  the	name  of  the  filesystem  (e.g. "native" or "vfs" or "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.

TCL_FILESYSTEM
       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
       optional	 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 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_FSCopyFileProc followed by Tcl_FSDeleteFileProc, and if Tcl_FSCopy-
       FileProc is not implemented there is a further fallback).  However,  if
       a  Tcl_FSRenameFile 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.

       As an example, 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 - fallback will occur at Tcl level */
		  NULL,
		  /* No rename file - fallback will occur at Tcl level */
		  NULL,
		  /* No copy directory - fallback will occur at Tcl level */
		  NULL,
		  /* Core will use stat for lstat */
		  NULL,
		  /* No load - fallback on core implementation */
		  NULL,
		  /* We don't need a getcwd or chdir - fallback on Tcl's versions */
		  NULL,
		  NULL
	      };

       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.

TYPENAME
       The typeName field contains a null-terminated  string  that  identifies
       the type of the filesystem implemented, e.g.  native or 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
       release.

VERSION
       The version field should be set to TCL_FILESYSTEM_VERSION_1.

FILESYSTEM INFRASTRUCTURE
       These fields contain 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
       representations.

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_FSPathInFilesystemProc for this filesystem always immediately  cre-
       ates 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' operat-
       ing on symbolic links.  This function may be  called  with  'nextCheck-
       point'  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 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.
       Must be implemented, otherwise the  file	 separator  command  will  not
       function	 correctly.  The usual return value will be a Tcl_Obj contain-
       ing the string "/".

	      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
       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 creation 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  file	system
       object)	whose  name is pathname.  If pathname is a symbolic link, then
       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 imple-
       mented 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
       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
       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
       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 standard
       channels, stdin, stdout or stderr was previously	 closed,  the  act  of
       creating the new channel also assigns it as a replacement for the stan-
       dard channel.

MATCHINDIRECTORYPROC
       Function to process a Tcl_FSMatchInDirectory()  call.   If  not	imple-
       mented,	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 *result,
		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;
       on  a TCL_OK result, results should be added to the result object given
       (which can be assumed to be a valid unshared Tcl	 list).	  The  matches
       added  to  result 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 result; 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
       implement 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 is a standard Tcl result indicating whether  an	 error
       occurred in the process.

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, which should call Tcl_DecrRefCount when
       the result 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. 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 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
       instead return NULL and place a Tcl list into the given objPtrRef.  Tcl
       will  take  that list and first increment its refCount before using it.
       On completion of that use, Tcl will decrement its refCount.   Hence  if
       the  list should be disposed of by Tcl when done, it should have a ref-
       Count of zero, and if the list should not be disposed of, the  filesys-
       tem should ensure it retains a refCount on the object.

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 refCount of zero.	 Either way we
       must either store it somewhere (e.g. the Tcl result), or Incr/Decr  its
       refCount 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
       error.  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
       unless 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
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.
       Therefore  it  need  only  be implemented if the filesystem can perform
       that action 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 Tcl_FSCopyDirectoryProc when needed to  copy
       them (even if they are symbolic links to directories).

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.

COPYDIRECTORYPROC
       Function	 to process a Tcl_FSCopyDirectory() call.  If not implemented,
       Tcl will fall back on a	recursive  create-dir,	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
       errorPtr.  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 func-
       tion is much simpler than the Tcl level 'file copy' subcommand).

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
       procedure will be called with the  given	 Tcl_LoadHandle	 as  its  only
       parameter when Tcl needs to unload the file.

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
       implement 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 dirName is a valid, accessible
       directory in their filesystem.  They  need  not	remember  the  result,
       since  that  will  be automatically remembered for use by GetCwd.  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.

KEYWORDS
       stat access filesystem vfs

Tcl				      8.4			 Filesystem(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net