Tcl_FSAccess man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin 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.

       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).

       Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
       but returns a character string or NULL.

       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,
       but on a TCL_OK result, the interpreter should  not  be	modified,  but
       rather results should be added to the result object given (which can be
       assumed to be a valid 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.

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]

List of man pages available for OpenDarwin

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