1Filesystem(3)               Tcl Library Procedures               Filesystem(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_FSRegister,   Tcl_FSUnregister,   Tcl_FSData,  Tcl_FSMountsChanged,
9       Tcl_FSGetFileSystemForPath,     Tcl_FSGetPathType,      Tcl_FSCopyFile,
10       Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRe‐
11       moveDirectory,  Tcl_FSRenameFile,  Tcl_FSListVolumes,   Tcl_FSEvalFile,
12       Tcl_FSEvalFileEx,  Tcl_FSLoadFile,  Tcl_FSMatchInDirectory, Tcl_FSLink,
13       Tcl_FSLstat,   Tcl_FSUtime,   Tcl_FSFileAttrsGet,   Tcl_FSFileAttrsSet,
14       Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel,
15       Tcl_FSGetCwd,   Tcl_FSChdir,    Tcl_FSPathSeparator,    Tcl_FSJoinPath,
16       Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoin‐
17       ToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep,  Tcl_FSGetTrans‐
18       latedPath,      Tcl_FSGetTranslatedStringPath,     Tcl_FSNewNativePath,
19       Tcl_FSGetNativePath, Tcl_FSFileSystemInfo,  Tcl_AllocStatBuf  -  proce‐
20       dures to interact with any filesystem
21

SYNOPSIS

23       #include <tcl.h>
24
25       int
26       Tcl_FSRegister(clientData, fsPtr)
27
28       int
29       Tcl_FSUnregister(fsPtr)
30
31       ClientData
32       Tcl_FSData(fsPtr)
33
34       void
35       Tcl_FSMountsChanged(fsPtr)
36
37       Tcl_Filesystem*
38       Tcl_FSGetFileSystemForPath(pathPtr)
39
40       Tcl_PathType
41       Tcl_FSGetPathType(pathPtr)
42
43       int
44       Tcl_FSCopyFile(srcPathPtr, destPathPtr)
45
46       int
47       Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)
48
49       int
50       Tcl_FSCreateDirectory(pathPtr)
51
52       int
53       Tcl_FSDeleteFile(pathPtr)
54
55       int
56       Tcl_FSRemoveDirectory(pathPtr, int recursive, errorPtr)
57
58       int
59       Tcl_FSRenameFile(srcPathPtr, destPathPtr)
60
61       Tcl_Obj*
62       Tcl_FSListVolumes(void)
63
64       int                                                                     │
65       Tcl_FSEvalFileEx(interp, pathPtr, encodingName)                         │
66
67       int
68       Tcl_FSEvalFile(interp, pathPtr)
69
70       int
71       Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
72                      handlePtr, unloadProcPtr)
73
74       int
75       Tcl_FSMatchInDirectory(interp, resultPtr, pathPtr, pattern, types)
76
77       Tcl_Obj*
78       Tcl_FSLink(linkNamePtr, toPtr, linkAction)
79
80       int
81       Tcl_FSLstat(pathPtr, statPtr)
82
83       int
84       Tcl_FSUtime(pathPtr, tval)
85
86       int
87       Tcl_FSFileAttrsGet(interp, int index, pathPtr, objPtrRef)
88
89       int
90       Tcl_FSFileAttrsSet(interp, int index, pathPtr, Tcl_Obj *objPtr)
91
92       const char**
93       Tcl_FSFileAttrStrings(pathPtr, objPtrRef)
94
95       int
96       Tcl_FSStat(pathPtr, statPtr)
97
98       int
99       Tcl_FSAccess(pathPtr, mode)
100
101       Tcl_Channel
102       Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)
103
104       Tcl_Obj*
105       Tcl_FSGetCwd(interp)
106
107       int
108       Tcl_FSChdir(pathPtr)
109
110       Tcl_Obj*
111       Tcl_FSPathSeparator(pathPtr)
112
113       Tcl_Obj*
114       Tcl_FSJoinPath(listObj, elements)
115
116       Tcl_Obj*
117       Tcl_FSSplitPath(pathPtr, lenPtr)
118
119       int
120       Tcl_FSEqualPaths(firstPtr, secondPtr)
121
122       Tcl_Obj*
123       Tcl_FSGetNormalizedPath(interp, pathPtr)
124
125       Tcl_Obj*
126       Tcl_FSJoinToPath(basePtr, objc, objv)
127
128       int
129       Tcl_FSConvertToPathType(interp, pathPtr)
130
131       ClientData
132       Tcl_FSGetInternalRep(pathPtr, fsPtr)
133
134       Tcl_Obj *
135       Tcl_FSGetTranslatedPath(interp, pathPtr)
136
137       const char *
138       Tcl_FSGetTranslatedStringPath(interp, pathPtr)
139
140       Tcl_Obj*
141       Tcl_FSNewNativePath(fsPtr, clientData)
142
143       const char *
144       Tcl_FSGetNativePath(pathPtr)
145
146       Tcl_Obj*
147       Tcl_FSFileSystemInfo(pathPtr)
148
149       Tcl_StatBuf*
150       Tcl_AllocStatBuf()
151

ARGUMENTS

153       Tcl_Filesystem *fsPtr (in)                         Points  to  a struc‐
154                                                          ture containing  the
155                                                          addresses  of proce‐
156                                                          dures  that  can  be
157                                                          called   to  perform
158                                                          the various filesys‐
159                                                          tem operations.
160
161       Tcl_Obj *pathPtr (in)                              The path represented
162                                                          by  this  object  is
163                                                          used  for the opera‐
164                                                          tion  in   question.
165                                                          If  the  object does
166                                                          not already have  an
167                                                          internal path repre‐
168                                                          sentation,  it  will
169                                                          be converted to have
170                                                          one.
171
172       Tcl_Obj *srcPathPtr (in)                           As for pathPtr,  but
173                                                          used  for the source
174                                                          file for a  copy  or
175                                                          rename operation.
176
177       Tcl_Obj *destPathPtr (in)                          As  for pathPtr, but
178                                                          used for the  desti‐
179                                                          nation  filename for
180                                                          a  copy  or   rename
181                                                          operation.
182
183       const char *encodingName (in)                      The  encoding of the
184                                                          data stored  in  the
185                                                          file  identified  by
186                                                          pathPtr  and  to  be
187                                                          evaluated.
188
189       const char *pattern (in)                           Only files or direc‐
190                                                          tories matching this
191                                                          pattern    will   be
192                                                          returned.
193
194       Tcl_GlobTypeData *types (in)                       Only files or direc‐
195                                                          tories  matching the
196                                                          type    descriptions
197                                                          contained   in  this
198                                                          structure  will   be
199                                                          returned.       This
200                                                          parameter   may   be
201                                                          NULL.
202
203       Tcl_Interp *interp (in)                            Interpreter  to  use
204                                                          either for  results,
205                                                          evaluation,       or
206                                                          reporting error mes‐
207                                                          sages.
208
209       ClientData clientData (in)                         The  native descrip‐
210                                                          tion  of  the   path
211                                                          object to create.
212
213       Tcl_Obj *firstPtr (in)                             The   first  of  two
214                                                          path objects to com‐
215                                                          pare.    The  object
216                                                          may be converted  to
217                                                          path type.
218
219       Tcl_Obj *secondPtr (in)                            The  second  of  two
220                                                          path objects to com‐
221                                                          pare.    The  object
222                                                          may be converted  to
223                                                          path type.
224
225       Tcl_Obj *listObj (in)                              The   list  of  path
226                                                          elements to  operate
227                                                          on with a join oper‐
228                                                          ation.
229
230       int elements (in)                                  If non-negative, the
231                                                          number  of  elements
232                                                          in the listObj which
233                                                          should   be   joined
234                                                          together.  If  nega‐
235                                                          tive,  then all ele‐
236                                                          ments are joined.
237
238       Tcl_Obj **errorPtr (out)                           In the  case  of  an
239                                                          error,  filled  with
240                                                          an object containing
241                                                          the name of the file
242                                                          which   caused    an
243                                                          error in the various
244                                                          copy/rename   opera‐
245                                                          tions.
246
247       Tcl_Obj **objPtrRef (out)                          Filled    with    an
248                                                          object    containing
249                                                          the  result  of  the
250                                                          operation.
251
252       Tcl_Obj *resultPtr (out)                           Pre-allocated object
253                                                          in  which  to  store
254                                                          (using   Tcl_ListOb‐
255                                                          jAppendElement)  the
256                                                          list  of  files   or
257                                                          directories    which
258                                                          are     successfully
259                                                          matched.
260
261       int mode (in)                                      Mask  consisting  of
262                                                          one or more of R_OK,
263                                                          W_OK, X_OK and F_OK.
264                                                          R_OK, W_OK and  X_OK
265                                                          request     checking
266                                                          whether   the   file
267                                                          exists    and    has
268                                                          read,   write    and
269                                                          execute      permis‐
270                                                          sions, respectively.
271                                                          F_OK  just  requests
272                                                          checking   for   the
273                                                          existence   of   the
274                                                          file.
275
276       Tcl_StatBuf *statPtr (out)                         The  structure  that
277                                                          contains  the result
278                                                          of a stat  or  lstat
279                                                          operation.
280
281       const char *sym1 (in)                              Name  of a procedure
282                                                          to look  up  in  the
283                                                          file's symbol table
284
285       const char *sym2 (in)                              Name  of a procedure
286                                                          to look  up  in  the
287                                                          file's symbol table
288
289       Tcl_PackageInitProc **proc1Ptr (out)               Filled with the init
290                                                          function  for   this
291                                                          code.
292
293       Tcl_PackageInitProc **proc2Ptr (out)               Filled    with   the
294                                                          safe-init   function
295                                                          for this code.
296
297       ClientData *clientDataPtr (out)                    Filled    with   the
298                                                          clientData value  to
299                                                          pass  to this code's
300                                                          unload function when
301                                                          it is called.
302
303       Tcl_LoadHandle *handlePtr (out)                    Filled    with    an
304                                                          abstract token  rep‐
305                                                          resenting the loaded
306                                                          file.
307
308       Tcl_FSUnloadFileProc **unloadProcPtr (out)         Filled   with    the
309                                                          function  to  use to
310                                                          unload this piece of
311                                                          code.
312
313       utimbuf *tval (in)                                 The access and modi‐
314                                                          fication  times   in
315                                                          this  structure  are
316                                                          read and used to set
317                                                          those  values  for a
318                                                          given file.
319
320       const char *modeString (in)                        Specifies  how   the
321                                                          file    is   to   be
322                                                          accessed.  May  have
323                                                          any  of  the  values
324                                                          allowed for the mode
325                                                          argument  to the Tcl
326                                                          open command.
327
328       int permissions (in)                               POSIX-style  permis‐
329                                                          sion  flags  such as
330                                                          0644.  If a new file
331                                                          is   created,  these
332                                                          permissions will  be
333                                                          set  on  the created
334                                                          file.
335
336       int *lenPtr (out)                                  If non-NULL,  filled
337                                                          with  the  number of
338                                                          elements   in    the
339                                                          split path.
340
341       Tcl_Obj *basePtr (in)                              The  base path on to
342                                                          which  to  join  the
343                                                          given elements.  May
344                                                          be NULL.
345
346       int objc (in)                                      The number  of  ele‐
347                                                          ments in objv.
348
349       Tcl_Obj *const objv[] (in)                         The elements to join
350                                                          to  the  given  base
351                                                          path.
352
353       Tcl_Obj *linkNamePtr (in)                          The name of the link
354                                                          to  be  created   or
355                                                          read.
356
357       Tcl_Obj *toPtr (in)                                What the link called
358                                                          linkNamePtr   should
359                                                          be   linked  to,  or
360                                                          NULL if the symbolic
361                                                          link   specified  by
362                                                          linkNamePtr is to be
363                                                          read.
364
365       int linkAction (in)                                OR-ed combination of
366                                                          flags     indicating
367                                                          what  kind  of  link
368                                                          should  be   created
369                                                          (will  be ignored if
370                                                          toPtr   is    NULL).
371                                                          Valid  bits  to  set
372                                                          are  TCL_CREATE_SYM‐
373                                                          BOLIC_LINK       and
374                                                          TCL_CRE‐
375                                                          ATE_HARD_LINK.  When
376                                                          both flags  are  set
377                                                          and  the  underlying
378                                                          filesystem  can   do
379                                                          either,     symbolic
380                                                          links are preferred.
381_________________________________________________________________
382
383

DESCRIPTION

385       There are several reasons for calling the Tcl_FS  API  functions  (e.g.
386       Tcl_FSAccess and Tcl_FSStat) rather than calling system level functions
387       like access and stat directly.  First, they will  work  cross-platform,
388       so  an  extension  which  calls them should work unmodified on Unix and
389       Windows.  Second, the Windows implementation of some of these functions
390       fixes some bugs in the system level calls.  Third, these function calls
391       deal with any “Utf to platform-native” path conversions  which  may  be
392       required  (and  may  cache  the results of such conversions for greater
393       efficiency on subsequent calls).  Fourth, and perhaps most importantly,
394       all  of  these  functions  are “virtual filesystem aware”.  Any virtual
395       filesystem  (VFS  for  short)  which  has  been   registered   (through
396       Tcl_FSRegister)  may reroute file access to alternative media or access
397       methods.  This means that all of these  functions  (and  therefore  the
398       corresponding  file,  glob,  pwd,  cd, open, etc.  Tcl commands) may be
399       operate on “files” which are not native files in the native filesystem.
400       This  also  means  that any Tcl extension which accesses the filesystem
401       (FS for short) through this API is  automatically  “virtual  filesystem
402       aware”.   Of  course,  if  an  extension accesses the native filesystem
403       directly (through platform-specific APIs, for example), then Tcl cannot
404       intercept such calls.
405
406       If appropriate VFSes have been registered, the “files” may, to give two
407       examples, be remote (e.g. situated on a remote ftp server) or  archived
408       (e.g.  lying  inside a .zip archive).  Such registered filesystems pro‐
409       vide a lookup table of functions to implement all or some of the  func‐
410       tionality  listed  here.  Finally, the Tcl_FSStat and Tcl_FSLstat calls
411       abstract away from what the “struct stat” buffer is  actually  declared
412       to  be, allowing the same code to be used both on systems with and sys‐
413       tems without support for files larger than 2GB in size.
414
415       The Tcl_FS API is objectified and may  cache  internal  representations
416       and  other  path-related  strings (e.g. the current working directory).
417       One side-effect of this is that one must not pass  in  objects  with  a
418       reference  count of zero to any of these functions.  If such calls were
419       handled, they might result in memory leaks (under  some  circumstances,
420       the  filesystem  code  may  wish to retain a reference to the passed in
421       object, and so one must not  assume  that  after  any  of  these  calls
422       return,  the  object  still has a reference count of zero - it may have
423       been incremented) or in a direct segmentation fault  (or  other  memory
424       access  error)  due to the object being freed part way through the com‐
425       plex object manipulation required to ensure that the path is fully nor‐
426       malized  and absolute for filesystem determination.  The practical les‐
427       son to learn from this is that
428              Tcl_Obj *path = Tcl_NewStringObj(...);
429              Tcl_FSWhatever(path);
430              Tcl_DecrRefCount(path);
431       is wrong, and may cause memory errors. The path must have its reference
432       count  incremented  before passing it in, or decrementing it.  For this
433       reason, objects with a reference count of zero are considered not to be
434       valid filesystem paths and calling any Tcl_FS API function with such an
435       object will result in no action being taken.
436
437   FS API FUNCTIONS
438       Tcl_FSCopyFile attempts to copy the file given  by  srcPathPtr  to  the
439       path name given by destPathPtr.  If the two paths given lie in the same
440       filesystem (according to Tcl_FSGetFileSystemForPath) then that filesys‐
441       tem's  “copy  file”  function is called (if it is non-NULL).  Otherwise
442       the function returns -1 and sets the errno global  C  variable  to  the
443       “EXDEV” POSIX error code (which signifies a “cross-domain link”).
444
445       Tcl_FSCopyDirectory  attempts to copy the directory given by srcPathPtr
446       to the path name given by destPathPtr.  If the two paths given  lie  in
447       the same filesystem (according to Tcl_FSGetFileSystemForPath) then that
448       filesystem's “copy file” function is called (if it is non-NULL).   Oth‐
449       erwise  the function returns -1 and sets the errno global C variable to
450       the “EXDEV” POSIX error code (which signifies a “cross-domain link”).
451
452       Tcl_FSCreateDirectory attempts to create the directory given by pathPtr
453       by calling the owning filesystem's “create directory” function.
454
455       Tcl_FSDeleteFile  attempts to delete the file given by pathPtr by call‐
456       ing the owning filesystem's “delete file” function.
457
458       Tcl_FSRemoveDirectory attempts to remove the directory given by pathPtr
459       by calling the owning filesystem's “remove directory” function.
460
461       Tcl_FSRenameFile attempts to rename the file or directory given by src‐
462       PathPtr to the path name given by destPathPtr.  If the two paths  given
463       lie  in  the  same filesystem (according to Tcl_FSGetFileSystemForPath)
464       then that filesystem's “rename file” function is called (if it is  non-
465       NULL).   Otherwise  the function returns -1 and sets the errno global C
466       variable to the “EXDEV” POSIX error code  (which  signifies  a  “cross-
467       domain link”).
468
469       Tcl_FSListVolumes calls each filesystem which has a non-NULL “list vol‐
470       umes” function and asks them to return their list of root volumes.   It
471       accumulates the return values in a list which is returned to the caller
472       (with a reference count of 0).
473
474       Tcl_FSEvalFileEx reads the file given by  pathPtr  using  the  encoding │
475       identified  by encodingName and evaluates its contents as a Tcl script. │
476       It returns the same information as Tcl_EvalObjEx.  If  encodingName  is │
477       NULL,  the  system  encoding is used for reading the file contents.  If │
478       the file could not be read then a Tcl error is returned to describe why │
479       the  file  could  not be read.  The eofchar for files is “\32” (^Z) for │
480       all platforms.  If you require a “^Z” in code  for  string  comparison, │
481       you can use “\032” or “\u001a”, which will be safely substituted by the │
482       Tcl interpreter into “^Z”.  Tcl_FSEvalFile  is  a  simpler  version  of │
483       Tcl_FSEvalFileEx  that always uses the system encoding when reading the │
484       file.
485
486       Tcl_FSLoadFile dynamically loads a binary code  file  into  memory  and
487       returns  the  addresses of two procedures within that file, if they are
488       defined.  The appropriate function for the filesystem to which  pathPtr
489       belongs  will  be  called.   If that filesystem does not implement this
490       function (most virtual filesystems will not, because of OS  limitations
491       in  dynamically loading binary code), Tcl will attempt to copy the file
492       to a temporary directory and load that temporary file.
493
494       Returns a standard Tcl completion code.  If an error occurs,  an  error
495       message is left in the interp's result.
496
497       Tcl_FSMatchInDirectory  is used by the globbing code to search a direc‐
498       tory for all files which match a given pattern.  The appropriate  func‐
499       tion for the filesystem to which pathPtr belongs will be called.
500
501       The  return  value is a standard Tcl result indicating whether an error
502       occurred in globbing.  Error messages  are  placed  in  interp  (unless
503       interp  is  NULL, which is allowed), but good results are placed in the
504       resultPtr given.
505
506       Note that the glob code implements recursive  patterns  internally,  so
507       this  function  will  only ever be passed simple patterns, which can be
508       matched using the logic of string match.  To handle recursion, Tcl will
509       call  this  function  frequently  asking  only  for  directories  to be
510       returned.  A special case of being called with a NULL pattern indicates
511       that the path needs to be checked only for the correct type.
512
513       Tcl_FSLink  replaces the library version of readlink, and extends it to
514       support the creation  of  links.   The  appropriate  function  for  the
515       filesystem to which linkNamePtr belongs will be called.
516
517       If the toPtr is NULL, a “read link” action is performed.  The result is
518       a Tcl_Obj specifying  the  contents  of  the  symbolic  link  given  by
519       linkNamePtr,  or  NULL  if  the  link could not be read.  The result is
520       owned by the caller, which should call Tcl_DecrRefCount when the result
521       is  no  longer  needed.   If the toPtr is not NULL, Tcl should create a
522       link of one of the types passed in in the linkAction flag.   This  flag
523       is   an  ORed  combination  of  TCL_CREATE_SYMBOLIC_LINK  and  TCL_CRE‐
524       ATE_HARD_LINK.  Where a choice exists  (i.e.  more  than  one  flag  is
525       passed  in),  the  Tcl  convention is to prefer symbolic links.  When a
526       link is successfully created, the return value should be  toPtr  (which
527       is  therefore  already  owned by the caller).  If unsuccessful, NULL is
528       returned.
529
530       Tcl_FSLstat fills the stat structure statPtr with information about the
531       specified  file.   You do not need any access rights to the file to get
532       this information but you need search rights to all directories named in
533       the path leading to the file.  The stat structure includes info regard‐
534       ing device, inode (always 0 on Windows), privilege mode, nlink  (always
535       1  on  Windows),  user  id (always 0 on Windows), group id (always 0 on
536       Windows), rdev (same as device on Windows),  size,  last  access  time,
537       last modification time, and last metadata change time.
538
539       If  path exists, Tcl_FSLstat returns 0 and the stat structure is filled
540       with data.  Otherwise, -1 is returned, and no stat info is given.
541
542       Tcl_FSUtime replaces the library version of utime.
543
544       This returns 0 on success and -1 on error (as per the utime  documenta‐
545       tion).  If successful, the function will update the “atime” and “mtime”
546       values of the file given.
547
548       Tcl_FSFileAttrsGet  implements  read  access  for  the  hookable   file
549       attributes  subcommand.  The appropriate function for the filesystem to
550       which pathPtr belongs will be called.
551
552       If the result is TCL_OK, then an object was placed in objPtrRef,  which
553       will only be temporarily valid (unless Tcl_IncrRefCount is called).
554
555       Tcl_FSFileAttrsSet  implements  write  access  for  the  hookable  file
556       attributes subcommand.  The appropriate function for the filesystem  to
557       which pathPtr belongs will be called.
558
559       Tcl_FSFileAttrStrings  implements  part of the hookable file attributes
560       subcommand.  The appropriate function for the filesystem to which path‐
561       Ptr belongs will be called.
562
563       The  called  procedure  may  either  return an array of strings, or may
564       instead return NULL and place a Tcl list into the given objPtrRef.  Tcl
565       will  take  that  list  and  first increment its reference count before
566       using it.  On completion of that use, Tcl will decrement its  reference
567       count.   Hence  if  the list should be disposed of by Tcl when done, it
568       should have a reference count of zero, and if the list  should  not  be
569       disposed  of, the filesystem should ensure it retains a reference count
570       to the object.
571
572       Tcl_FSAccess checks whether the process would be allowed to read, write
573       or  test  for  existence of the file (or other filesystem object) whose
574       name is pathname.   If pathname is a symbolic link on Unix,  then  per‐
575       missions of the file referred by this symbolic link are tested.
576
577       On  success  (all requested permissions granted), zero is returned.  On
578       error (at least one bit in mode asked for a permission that is  denied,
579       or some other error occurred), -1 is returned.
580
581       Tcl_FSStat  fills the stat structure statPtr with information about the
582       specified file.  You do not need any access rights to the file  to  get
583       this information but you need search rights to all directories named in
584       the path leading to the file.  The stat structure includes info regard‐
585       ing  device, inode (always 0 on Windows), privilege mode, nlink (always
586       1 on Windows), user id (always 0 on Windows), group  id  (always  0  on
587       Windows),  rdev  (same  as  device on Windows), size, last access time,
588       last modification time, and last metadata change time.
589
590       If path exists, Tcl_FSStat returns 0 and the stat structure  is  filled
591       with data.  Otherwise, -1 is returned, and no stat info is given.
592
593       Tcl_FSOpenFileChannel  opens  a file specified by pathPtr and returns a
594       channel handle that can be used to perform  input  and  output  on  the
595       file.  This  API is modeled after the fopen procedure of the Unix stan‐
596       dard I/O library.  The syntax and meaning of all arguments  is  similar
597       to  those  given  in  the  Tcl open command when opening a file.  If an
598       error occurs while opening the channel,  Tcl_FSOpenFileChannel  returns
599       NULL  and  records  a  POSIX  error  code  that  can  be retrieved with
600       Tcl_GetErrno.  In addition, if interp is non-NULL,  Tcl_FSOpenFileChan‐
601       nel leaves an error message in interp's result after any error.
602
603       The  newly  created  channel  is  not registered in the supplied inter‐
604       preter; to register it, use Tcl_RegisterChannel.  If one of  the  stan‐
605       dard  channels,  stdin, stdout or stderr was previously closed, the act
606       of creating the new channel also assigns it as a  replacement  for  the
607       standard channel.
608
609       Tcl_FSGetCwd replaces the library version of getcwd.
610
611       It  returns  the  Tcl library's current working directory.  This may be
612       different to the native platform's  working  directory,  which  happens
613       when the current working directory is not in the native filesystem.
614
615       The  result is a pointer to a Tcl_Obj specifying the current directory,
616       or NULL if the current directory could not be determined.  If  NULL  is
617       returned, an error message is left in the interp's result.
618
619       The  result already has its reference count incremented for the caller.
620       When it is no longer needed, that  reference  count  should  be  decre‐
621       mented.   This  is needed for thread-safety purposes, to allow multiple
622       threads to access  this  and  related  functions,  while  ensuring  the
623       results are always valid.
624
625       Tcl_FSChdir replaces the library version of chdir.  The path is normal‐
626       ized and then passed to  the  filesystem  which  claims  it.   If  that
627       filesystem  does  not  implement  this function, Tcl will fallback to a
628       combination of stat and access to check whether  the  directory  exists
629       and has appropriate permissions.
630
631       For  results, see chdir documentation.  If successful, we keep a record
632       of  the  successful  path  in  cwdPathPtr  for  subsequent   calls   to
633       Tcl_FSGetCwd.
634
635       Tcl_FSPathSeparator returns the separator character to be used for most
636       specific element of the path specified by pathPtr (i.e. the  last  part
637       of the path).
638
639       The separator is returned as a Tcl_Obj containing a string of length 1.
640       If the path is invalid, NULL is returned.
641
642       Tcl_FSJoinPath takes the given Tcl_Obj, which  must  be  a  valid  list
643       (which  is  allowed to have a reference count of zero), and returns the
644       path object given by considering the first elements elements  as  valid
645       path segments (each path segment may be a complete path, a partial path
646       or just a single possible directory or file name).  If any path segment
647       is  actually  an  absolute  path, then all prior path segments are dis‐
648       carded.  If elements is less than 0, we use the entire list.
649
650       It is possible that the returned object is actually an element  of  the
651       given  list, so the caller should be careful to increment the reference
652       count of the result before freeing the list.
653
654       The returned object, typically with a reference count of zero  (but  it
655       could  be shared under some conditions), contains the joined path.  The
656       caller must add a reference count to the object before  using  it.   In
657       particular,  the returned object could be an element of the given list,
658       so freeing the list might free the object prematurely if  no  reference
659       count  has  been  taken.   If  the number of elements is zero, then the
660       returned object will be an empty-string Tcl_Obj.
661
662       Tcl_FSSplitPath takes the given Tcl_Obj, which should be a valid  path,
663       and  returns  a Tcl list object containing each segment of that path as
664       an element.  It returns a list object with a reference count  of  zero.
665       If  the passed in lenPtr is non-NULL, the variable it points to will be
666       updated to contain the number of elements in the returned list.
667
668       Tcl_FSEqualPaths tests whether the two paths given represent  the  same
669       filesystem object
670
671       It  returns  1 if the paths are equal, and 0 if they are different.  If
672       either path is NULL, 0 is always returned.
673
674       Tcl_FSGetNormalizedPath this important  function  attempts  to  extract
675       from  the  given Tcl_Obj a unique normalized path representation, whose
676       string value can be used as a unique identifier for the file.
677
678       It returns the normalized path object, owned by Tcl,  or  NULL  if  the
679       path  was  invalid  or  could  otherwise not be successfully converted.
680       Extraction of absolute, normalized paths is very efficient (because the
681       filesystem  operates on these representations internally), although the
682       result when the filesystem contains numerous symbolic links may not  be
683       the most user-friendly version of a path.  The return value is owned by
684       Tcl and has a lifetime equivalent to that  of  the  pathPtr  passed  in
685       (unless  that  is  a  relative  path, in which case the normalized path
686       object may be freed any time the cwd  changes)  -  the  caller  can  of
687       course  increment  the  refCount  if  it  wishes to maintain a copy for
688       longer.
689
690       Tcl_FSJoinToPath takes the given object,  which  should  usually  be  a
691       valid  path  or  NULL,  and  joins  onto it the array of paths segments
692       given.
693
694       Returns object, typically with refCount of zero (but it could be shared
695       under  some  conditions),  containing the joined path.  The caller must
696       add a refCount to the object before using it.  If any  of  the  objects
697       passed into this function (pathPtr or path elements) have a refCount of
698       zero, they will be freed when this function returns.
699
700       Tcl_FSConvertToPathType tries to convert the given Tcl_Obj to  a  valid
701       Tcl path type, taking account of the fact that the cwd may have changed
702       even if this object is already supposedly of  the  correct  type.   The
703       filename may begin with “~” (to indicate current user's home directory)
704       or “~<user>” (to indicate any user's home directory).
705
706       If the conversion succeeds (i.e. the object is a valid path in  one  of
707       the current filesystems), then TCL_OK is returned.  Otherwise TCL_ERROR
708       is returned, and an error message may be left in the interpreter.
709
710       Tcl_FSGetInternalRep extracts the internal representation  of  a  given
711       path  object, in the given filesystem.  If the path object belongs to a
712       different filesystem, we return NULL. If the internal representation is
713       currently  NULL, we attempt to generate it, by calling the filesystem's
714       Tcl_FSCreateInternalRepProc.
715
716       Returns NULL or a valid internal path  representation.   This  internal
717       representation  is cached, so that repeated calls to this function will
718       not require additional conversions.
719
720       Tcl_FSGetTranslatedPath attempts to extract the  translated  path  from
721       the given Tcl_Obj.
722
723       If  the translation succeeds (i.e. the object is a valid path), then it
724       is returned.  Otherwise NULL will be returned, and an error message may
725       be  left in the interpreter.  A “translated” path is one which contains
726       no “~” or “~user” sequences (these have been expanded to their  current
727       representation in the filesystem).  The object returned is owned by the
728       caller, which must store it or call Tcl_DecrRefCount to  ensure  memory
729       is  freed.  This function is of little practical use, and Tcl_FSGetNor‐
730       malizedPath or Tcl_GetNativePath are usually better  functions  to  use
731       for most purposes.
732
733       Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
734       but returns a character string or NULL.  The string returned is dynami‐
735       cally  allocated  and  owned by the caller, which must store it or call
736       ckfree to  ensure  it  is  freed.   Again,  Tcl_FSGetNormalizedPath  or
737       Tcl_GetNativePath  are  usually  better  functions to use for most pur‐
738       poses.
739
740       Tcl_FSNewNativePath performs something like the reverse  of  the  usual
741       obj->path->nativerep  conversions.   If  some  code retrieves a path in
742       native form (from, e.g. readlink or a native dialog), and that path  is
743       to be used at the Tcl level, then calling this function is an efficient
744       way of creating the appropriate path object type.
745
746       The resulting object is a pure “path” object, which will only receive a
747       UTF-8 string representation if that is required by some Tcl code.
748
749       Tcl_FSGetNativePath  is  for use by the Win/Unix native filesystems, so
750       that they can easily retrieve the native (char* or TCHAR*)  representa‐
751       tion  of  a  path.   This  function  is  a  convenience  wrapper around
752       Tcl_FSGetInternalRep, and assumes the native representation is  string-
753       based.   It  may  be  desirable  in the future to have non-string-based
754       native representations (for example, on MacOSX, a representation  using
755       a  fileSpec  of  FSRef structure would probably be more efficient).  On
756       Windows a full Unicode representation would allow for paths  of  unlim‐
757       ited length.  Currently the representation is simply a character string
758       which may contain either the relative path or a complete, absolute nor‐
759       malized  path  in the native encoding (complex conditions dictate which
760       of these will be provided, so neither can be relied  upon,  unless  the
761       path is known to be absolute).  If you need a native path which must be
762       absolute, then you should ask for the native version  of  a  normalized
763       path.  If for some reason a non-absolute, non-normalized version of the
764       path is  needed,  that  must  be  constructed  separately  (e.g.  using
765       Tcl_FSGetTranslatedPath).
766
767       The  native  representation  is  cached  so that repeated calls to this
768       function will not require additional conversions.  The return value  is
769       owned  by  Tcl  and  has  a  lifetime equivalent to that of the pathPtr
770       passed in (unless that is a relative path, in  which  case  the  native
771       representation may be freed any time the cwd changes).
772
773       Tcl_FSFileSystemInfo returns a list of two elements.  The first element
774       is the name  of  the  filesystem  (e.g.   “native”,  “vfs”,  “zip”,  or
775       “prowrap”, perhaps), and the second is the particular type of the given
776       path within that filesystem (which is filesystem dependent).  The  sec‐
777       ond  element  may be empty if the filesystem does not provide a further
778       categorization of files.
779
780       A valid list object is returned, unless the path object is  not  recog‐
781       nized, when NULL will be returned.
782
783       Tcl_FSGetFileSystemForPath  returns the a pointer to the Tcl_Filesystem
784       which accepts this path as valid.
785
786       If no filesystem will accept the path, NULL is returned.
787
788       Tcl_FSGetPathType determines whether the given path is relative to  the
789       current directory, relative to the current volume, or absolute.
790
791       It    returns   one   of   TCL_PATH_ABSOLUTE,   TCL_PATH_RELATIVE,   or
792       TCL_PATH_VOLUME_RELATIVE
793
794       Tcl_AllocStatBuf allocates a Tcl_StatBuf on the system heap (which  may
795       be  deallocated  by being passed to ckfree.)  This allows extensions to
796       invoke Tcl_FSStat and Tcl_FSLStat without being dependent on  the  size
797       of the buffer.  That in turn depends on the flags used to build Tcl.
798

THE VIRTUAL FILESYSTEM API

800       A filesystem provides a Tcl_Filesystem structure that contains pointers
801       to functions that implement the various  operations  on  a  filesystem;
802       these operations are invoked as needed by the generic layer, which gen‐
803       erally occurs through the functions listed above.
804
805       The Tcl_Filesystem structures are manipulated using the following meth‐
806       ods.
807
808       Tcl_FSRegister  takes  a  pointer  to  a  filesystem  structure  and an
809       optional piece of data to associated with that filesystem.  On  calling
810       this  function,  Tcl  will  attach  the filesystem to the list of known
811       filesystems, and it will become fully functional immediately.  Tcl does
812       not  check  if the same filesystem is registered multiple times (and in
813       general that is not a good thing to do).  TCL_OK will be returned.
814
815       Tcl_FSUnregister removes the given filesystem structure from  the  list
816       of  known  filesystems,  if  it  is  known, and returns TCL_OK.  If the
817       filesystem is not currently registered, TCL_ERROR is returned.
818
819       Tcl_FSData  will  return  the  ClientData  associated  with  the  given
820       filesystem, if that filesystem is registered.  Otherwise it will return
821       NULL.
822
823       Tcl_FSMountsChanged is used to inform the Tcl's core that  the  set  of
824       mount  points  for  the  given  (already  registered)  filesystem  have
825       changed, and that cached file representations may therefore  no  longer
826       be correct.
827
828   THE TCL_FILESYSTEM STRUCTURE
829       The Tcl_Filesystem structure contains the following fields:
830              typedef struct Tcl_Filesystem {
831                  const char *typeName;
832                  int structureLength;
833                  Tcl_FSVersion version;
834                  Tcl_FSPathInFilesystemProc *pathInFilesystemProc;
835                  Tcl_FSDupInternalRepProc *dupInternalRepProc;
836                  Tcl_FSFreeInternalRepProc *freeInternalRepProc;
837                  Tcl_FSInternalToNormalizedProc *internalToNormalizedProc;
838                  Tcl_FSCreateInternalRepProc *createInternalRepProc;
839                  Tcl_FSNormalizePathProc *normalizePathProc;
840                  Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc;
841                  Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc;
842                  Tcl_FSStatProc *statProc;
843                  Tcl_FSAccessProc *accessProc;
844                  Tcl_FSOpenFileChannelProc *openFileChannelProc;
845                  Tcl_FSMatchInDirectoryProc *matchInDirectoryProc;
846                  Tcl_FSUtimeProc *utimeProc;
847                  Tcl_FSLinkProc *linkProc;
848                  Tcl_FSListVolumesProc *listVolumesProc;
849                  Tcl_FSFileAttrStringsProc *fileAttrStringsProc;
850                  Tcl_FSFileAttrsGetProc *fileAttrsGetProc;
851                  Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
852                  Tcl_FSCreateDirectoryProc *createDirectoryProc;
853                  Tcl_FSRemoveDirectoryProc *removeDirectoryProc;
854                  Tcl_FSDeleteFileProc *deleteFileProc;
855                  Tcl_FSCopyFileProc *copyFileProc;
856                  Tcl_FSRenameFileProc *renameFileProc;
857                  Tcl_FSCopyDirectoryProc *copyDirectoryProc;
858                  Tcl_FSLstatProc *lstatProc;
859                  Tcl_FSLoadFileProc *loadFileProc;
860                  Tcl_FSGetCwdProc *getCwdProc;
861                  Tcl_FSChdirProc *chdirProc;
862              } Tcl_Filesystem;
863
864       Except  for the first three fields in this structure which contain sim‐
865       ple data elements, all entries contain addresses of functions called by
866       the  generic filesystem layer to perform the complete range of filesys‐
867       tem related actions.
868
869       The many functions in this structure are broken down into  three  cate‐
870       gories:  infrastructure  functions  (almost all of which must be imple‐
871       mented), operational functions (which must be implemented if a complete
872       filesystem  is  provided), and efficiency functions (which need only be
873       implemented if they can be done so efficiently, or if they  have  side-
874       effects  which  are  required by the filesystem; Tcl has less efficient
875       emulations it can fall back on).  It is important to note that, in  the
876       current version of Tcl, most of these fallbacks are only used to handle
877       commands initiated in Tcl, not in C. What this means is, that if a file
878       rename  command is issued in Tcl, and the relevant filesystem(s) do not
879       implement their Tcl_FSRenameFileProc, Tcl's core will instead  fallback
880       on a combination of other filesystem functions (it will use Tcl_FSCopy‐
881       FileProc followed by Tcl_FSDeleteFileProc, and if Tcl_FSCopyFileProc is
882       not  implemented there is a further fallback).  However, if a Tcl_FSRe‐
883       nameFileProc command is issued at the C level, no such fallbacks occur.
884       This  is  true except for the last four entries in the filesystem table
885       (lstat, load, getcwd and chdir) for which fallbacks do in fact occur at
886       the C level.
887
888       Any functions which take path names in Tcl_Obj form take those names in
889       UTF-8 form.  The filesystem infrastructure API is designed  to  support
890       efficient,  cached conversion of these UTF-8 paths to other native rep‐
891       resentations.
892
893   EXAMPLE FILESYSTEM DEFINITION
894       Here is the filesystem lookup table used by the “vfs”  extension  which
895       allows filesystem actions to be implemented in Tcl.
896              static Tcl_Filesystem vfsFilesystem = {
897                  "tclvfs",
898                  sizeof(Tcl_Filesystem),
899                  TCL_FILESYSTEM_VERSION_1,
900                  &VfsPathInFilesystem,
901                  &VfsDupInternalRep,
902                  &VfsFreeInternalRep,
903                  /* No internal to normalized, since we don't create
904                   * any pure 'internal' Tcl_Obj path representations */
905                  NULL,
906                  /* No create native rep function, since we don't use
907                   * it and don't choose to support uses of
908                   * Tcl_FSNewNativePath */
909                  NULL,
910                  /* Normalize path isn't needed - we assume paths only
911                   * have one representation */
912                  NULL,
913                  &VfsFilesystemPathType,
914                  &VfsFilesystemSeparator,
915                  &VfsStat,
916                  &VfsAccess,
917                  &VfsOpenFileChannel,
918                  &VfsMatchInDirectory,
919                  &VfsUtime,
920                  /* We choose not to support symbolic links inside our
921                   * VFS's */
922                  NULL,
923                  &VfsListVolumes,
924                  &VfsFileAttrStrings,
925                  &VfsFileAttrsGet,
926                  &VfsFileAttrsSet,
927                  &VfsCreateDirectory,
928                  &VfsRemoveDirectory,
929                  &VfsDeleteFile,
930                  /* No copy file; use the core fallback mechanism */
931                  NULL,
932                  /* No rename file; use the core fallback mechanism */
933                  NULL,
934                  /* No copy directory; use the core fallback mechanism */
935                  NULL,
936                  /* Core will use stat for lstat */
937                  NULL,
938                  /* No load; use the core fallback mechanism */
939                  NULL,
940                  /* We don't need a getcwd or chdir; the core's own
941                   * internal value is suitable */
942                  NULL,
943                  NULL
944              };
945

FILESYSTEM INFRASTRUCTURE

947       These  fields  contain basic information about the filesystem structure
948       and addresses of functions which are used  to  associate  a  particular
949       filesystem  with  a  file  path, and deal with the internal handling of
950       path representations, for example copying and freeing such  representa‐
951       tions.
952
953   TYPENAME
954       The  typeName  field  contains a null-terminated string that identifies
955       the type of the filesystem implemented, e.g.  “native”, “zip” or “vfs”.
956
957   STRUCTURE LENGTH
958       The    structureLength    field    is    generally    implemented    as
959       sizeof(Tcl_Filesystem),  and  is there to allow easier binary backwards
960       compatibility if the size of the structure  changes  in  a  future  Tcl
961       release.
962
963   VERSION
964       The version field should be set to TCL_FILESYSTEM_VERSION_1.
965
966   PATHINFILESYSTEMPROC
967       The pathInFilesystemProc field contains the address of a function which
968       is called to determine whether a given  path  object  belongs  to  this
969       filesystem or not.  Tcl will only call the rest of the filesystem func‐
970       tions with a path for which this function has returned TCL_OK.  If  the
971       path  does  not belong, -1 should be returned (the behaviour of Tcl for
972       any other return value is not defined).  If TCL_OK  is  returned,  then
973       the  optional  clientDataPtr  output parameter can be used to return an
974       internal (filesystem specific) representation of the path,  which  will
975       be  cached  inside the path object, and may be retrieved efficiently by
976       the other filesystem functions.  Tcl will simultaneously cache the fact
977       that this path belongs to this filesystem.  Such caches are invalidated
978       when filesystem structures are added or  removed  from  Tcl's  internal
979       list of known filesystems.
980
981              typedef int Tcl_FSPathInFilesystemProc(
982                      Tcl_Obj *pathPtr,
983                      ClientData *clientDataPtr);
984
985   DUPINTERNALREPPROC
986       This  function makes a copy of a path's internal representation, and is
987       called when Tcl needs to duplicate a path object.  If  NULL,  Tcl  will
988       simply  not copy the internal representation, which may then need to be
989       regenerated later.
990
991              typedef ClientData Tcl_FSDupInternalRepProc(
992                      ClientData clientData);
993
994   FREEINTERNALREPPROC
995       Free the internal representation.  This must be implemented if internal
996       representations  need freeing (i.e. if some memory is allocated when an
997       internal representation is generated), but may otherwise be NULL.
998
999              typedef void Tcl_FSFreeInternalRepProc(
1000                      ClientData clientData);
1001
1002   INTERNALTONORMALIZEDPROC
1003       Function to convert internal representation to a normalized path.  Only
1004       required   if   the  filesystem  creates  pure  path  objects  with  no
1005       string/path representation.  The return value is  a  Tcl  object  whose
1006       string representation is the normalized path.
1007
1008              typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
1009                      ClientData clientData);
1010
1011   CREATEINTERNALREPPROC
1012       Function  to  take a path object, and calculate an internal representa‐
1013       tion for it, and store that native representation in the  object.   May
1014       be   NULL   if  paths  have  no  internal  representation,  or  if  the
1015       Tcl_FSPathInFilesystemProc for this filesystem always immediately  cre‐
1016       ates an internal representation for paths it accepts.
1017
1018              typedef ClientData Tcl_FSCreateInternalRepProc(
1019                      Tcl_Obj *pathPtr);
1020
1021   NORMALIZEPATHPROC
1022       Function  to  normalize a path.  Should be implemented for all filesys‐
1023       tems which can have multiple string representations for the  same  path
1024       object.   In  Tcl,  every “path” must have a single unique “normalized”
1025       string representation.  Depending on the filesystem, there may be  more
1026       than  one  unnormalized string representation which refers to that path
1027       (e.g. a relative path, a path with  different  character  case  if  the
1028       filesystem  is  case  insensitive, a path contain a reference to a home
1029       directory such as “~”, a path containing symbolic links, etc).  If  the
1030       very  last  component  in the path is a symbolic link, it should not be
1031       converted into the object it points to (but its case or  other  aspects
1032       should  be made unique).  All other path components should be converted
1033       from symbolic links.  This one exception  is  required  to  agree  with
1034       Tcl's  semantics  with file delete, file rename, file copy operating on
1035       symbolic links.  This function may be called with nextCheckpoint either
1036       at the beginning of the path (i.e. zero), at the end of the path, or at
1037       any intermediate file separator in the path.  It will  never  point  to
1038       any  other  arbitrary  position  in  the path. In the last of the three
1039       valid cases, the implementation can assume that  the  path  up  to  and
1040       including the file separator is known and normalized.
1041
1042              typedef int Tcl_FSNormalizePathProc(
1043                      Tcl_Interp *interp,
1044                      Tcl_Obj *pathPtr,
1045                      int nextCheckpoint);
1046

FILESYSTEM OPERATIONS

1048       The  fields in this section of the structure contain addresses of func‐
1049       tions which are called to carry out the basic filesystem operations.  A
1050       filesystem which expects to be used with the complete standard Tcl com‐
1051       mand set must implement all of these.  If some of them are  not  imple‐
1052       mented,  then  certain  Tcl  commands  may fail when operating on paths
1053       within that filesystem.  However, in some instances this may be  desir‐
1054       able (for example, a read-only filesystem should not implement the last
1055       four functions, and a filesystem which does not support symbolic  links
1056       need  not  implement  the readlink function, etc.  The Tcl core expects
1057       filesystems to behave in this way).
1058
1059   FILESYSTEMPATHTYPEPROC
1060       Function to determine the type of a path in this  filesystem.   May  be
1061       NULL,  in  which case no type information will be available to users of
1062       the filesystem.  The “type” is used only  for  informational  purposes,
1063       and  should  be  returned  as  the string representation of the Tcl_Obj
1064       which is returned.  A typical return value might be “networked”,  “zip”
1065       or  “ftp”.   The  Tcl_Obj  result is owned by the filesystem and so Tcl
1066       will increment the refCount of that object if it  wishes  to  retain  a
1067       reference to it.
1068
1069              typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc(
1070                      Tcl_Obj *pathPtr);
1071
1072   FILESYSTEMSEPARATORPROC
1073       Function  to  return  the  separator  character(s) for this filesystem.
1074       This need only be implemented if the filesystem wishes to use a differ‐
1075       ent  separator than the standard string “/”.  Amongst other uses, it is
1076       returned by the file separator command.  The return value should be  an
1077       object with refCount of zero.
1078
1079              typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
1080                      Tcl_Obj *pathPtr);
1081
1082   STATPROC
1083       Function  to  process  a  Tcl_FSStat call.  Must be implemented for any
1084       reasonable filesystem, since many Tcl level commands  depend  crucially
1085       upon it (e.g. file atime, file isdirectory, file size, glob).
1086
1087              typedef int Tcl_FSStatProc(
1088                      Tcl_Obj *pathPtr,
1089                      Tcl_StatBuf *statPtr);
1090
1091       The  Tcl_FSStatProc  fills  the stat structure statPtr with information
1092       about the specified file.  You do not need any  access  rights  to  the
1093       file to get this information but you need search rights to all directo‐
1094       ries named in the  path  leading  to  the  file.   The  stat  structure
1095       includes  info regarding device, inode (always 0 on Windows), privilege
1096       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
1097       id  (always 0 on Windows), rdev (same as device on Windows), size, last
1098       access time, last modification time, and last metadata change time.
1099
1100       If the file represented by pathPtr exists, the Tcl_FSStatProc returns 0
1101       and the stat structure is filled with data.  Otherwise, -1 is returned,
1102       and no stat info is given.
1103
1104   ACCESSPROC
1105       Function to process a Tcl_FSAccess call.  Must be implemented  for  any
1106       reasonable  filesystem,  since many Tcl level commands depend crucially
1107       upon it (e.g. file exists, file readable).
1108
1109              typedef int Tcl_FSAccessProc(
1110                      Tcl_Obj *pathPtr,
1111                      int mode);
1112
1113       The Tcl_FSAccessProc checks whether the process  would  be  allowed  to
1114       read,  write  or  test  for  existence of the file (or other filesystem
1115       object) whose name is in pathPtr.  If the pathname refers to a symbolic
1116       link,  then  the permissions of the file referred by this symbolic link
1117       should be tested.
1118
1119       On success (all requested permissions granted), zero is  returned.   On
1120       error  (at least one bit in mode asked for a permission that is denied,
1121       or some other  error occurred), -1 is returned.
1122
1123   OPENFILECHANNELPROC
1124       Function to process a Tcl_FSOpenFileChannel call.  Must be  implemented
1125       for  any reasonable filesystem, since any operations which require open
1126       or accessing a file's contents will use it (e.g.  open,  encoding,  and
1127       many Tk commands).
1128
1129              typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
1130                      Tcl_Interp *interp,
1131                      Tcl_Obj *pathPtr,
1132                      int mode,
1133                      int permissions);
1134
1135       The  Tcl_FSOpenFileChannelProc  opens  a  file specified by pathPtr and
1136       returns a channel handle that can be used to perform input  and  output
1137       on the file.  This API is modeled after the fopen procedure of the Unix
1138       standard I/O library.  The syntax and meaning of all arguments is simi‐
1139       lar  to  those given in the Tcl open command when opening a file, where
1140       the mode argument  is  a  combination  of  the  POSIX  flags  O_RDONLY,
1141       O_WRONLY,  etc.   If  an  error  occurs  while opening the channel, the
1142       Tcl_FSOpenFileChannelProc returns NULL and records a POSIX  error  code
1143       that  can  be  retrieved  with Tcl_GetErrno.  In addition, if interp is
1144       non-NULL, the Tcl_FSOpenFileChannelProc  leaves  an  error  message  in
1145       interp's result after any error.
1146
1147       The  newly  created  channel must not registered in the supplied inter‐
1148       preter; that task is up to the caller of Tcl_FSOpenFileChannel (if nec‐
1149       essary).  If  one of the standard channels, stdin, stdout or stderr was
1150       previously closed, the act of creating the new channel also assigns  it
1151       as a replacement for the standard channel.
1152
1153   MATCHINDIRECTORYPROC
1154       Function to process a Tcl_FSMatchInDirectory call.  If not implemented,
1155       then glob and recursive copy  functionality  will  be  lacking  in  the
1156       filesystem  (and this may impact commands like encoding names which use
1157       glob functionality internally).
1158
1159              typedef int Tcl_FSMatchInDirectoryProc(
1160                      Tcl_Interp* interp,
1161                      Tcl_Obj *resultPtr,
1162                      Tcl_Obj *pathPtr,
1163                      const char *pattern,
1164                      Tcl_GlobTypeData *types);
1165
1166       The function should return all files or directories (or other  filesys‐
1167       tem  objects)  which  match the given pattern and accord with the types
1168       specification given.  There are two ways in which this function may  be
1169       called.   If pattern is NULL, then pathPtr is a full path specification
1170       of a single file or directory which should be checked for existence and
1171       correct type.  Otherwise, pathPtr is a directory, the contents of which
1172       the function should search for files or directories which have the cor‐
1173       rect  type.  In either case, pathPtr can be assumed to be both non-NULL
1174       and non-empty.  It is not currently  documented  whether  pathPtr  will
1175       have  a file separator at its end of not, so code should be flexible to
1176       both possibilities.
1177
1178       The return value is a standard Tcl result indicating whether  an  error
1179       occurred in the matching process.  Error messages are placed in interp,
1180       unless interp in NULL in which case no error message need be generated;
1181       on  a  TCL_OK  result,  results should be added to the resultPtr object
1182       given (which can be assumed to be a  valid  unshared  Tcl  list).   The
1183       matches  added  to  resultPtr  should  include any path prefix given in
1184       pathPtr (this usually means they will be absolute path specifications).
1185       Note  that  if  no  matches  are  found,  that simply leads to an empty
1186       result; errors are only signaled for actual file or filesystem problems
1187       which may occur during the matching process.
1188
1189       The  Tcl_GlobTypeData  structure passed in the types parameter contains
1190       the following fields:
1191              typedef struct Tcl_GlobTypeData {
1192                      /* Corresponds to bcdpfls as in 'find -t' */
1193                      int type;
1194                      /* Corresponds to file permissions */
1195                      int perm;
1196                      /* Acceptable mac type */
1197                      Tcl_Obj *macType;
1198                      /* Acceptable mac creator */
1199                      Tcl_Obj *macCreator;
1200              } Tcl_GlobTypeData;
1201
1202       There are two specific cases which it is important to handle correctly,
1203       both  when  types  is  non-NULL.  The two cases are when types->types &
1204       TCL_GLOB_TYPE_DIR or types->types & TCL_GLOB_TYPE_MOUNT are  true  (and
1205       in  particular  when the other flags are false).  In the first of these
1206       cases, the function must list the contained directories.  Tcl uses this
1207       to  implement  recursive  globbing,  so it is critical that filesystems
1208       implement directory matching correctly.  In the second of these  cases,
1209       with  TCL_GLOB_TYPE_MOUNT,  the  filesystem  must list the mount points
1210       which lie within the given pathPtr (and in this case, pathPtr need  not
1211       lie  within the same filesystem - different to all other cases in which
1212       this function is called).  Support for this is critical if  Tcl  is  to
1213       have seamless transitions between from one filesystem to another.
1214
1215   UTIMEPROC
1216       Function to process a Tcl_FSUtime call.  Required to allow setting (not
1217       reading) of times with file mtime,  file  atime  and  the  open-r/open-
1218       w/fcopy implementation of file copy.
1219
1220              typedef int Tcl_FSUtimeProc(
1221                      Tcl_Obj *pathPtr,
1222                      struct utimbuf *tval);
1223
1224       The  access  and  modification  times  of the file specified by pathPtr
1225       should be changed to the values given in the tval structure.
1226
1227       The return value should be 0 on success and -1 on an error, as with the
1228       system utime.
1229
1230   LINKPROC
1231       Function  to  process a Tcl_FSLink call.  Should be implemented only if
1232       the filesystem supports links, and may otherwise be NULL.
1233
1234              typedef Tcl_Obj* Tcl_FSLinkProc(
1235                      Tcl_Obj *linkNamePtr,
1236                      Tcl_Obj *toPtr,
1237                      int linkAction);
1238
1239       If toPtr is NULL, the function is being asked to read the contents of a
1240       link.   The  result  is  a  Tcl_Obj specifying the contents of the link
1241       given by linkNamePtr, or NULL if the  link  could  not  be  read.   The
1242       result  is owned by the caller (and should therefore have its ref count
1243       incremented before being returned).  Any callers should call  Tcl_Decr‐
1244       RefCount  on  this result when it is no longer needed.  If toPtr is not
1245       NULL, the function should attempt to create a link.  The result in this
1246       case should be toPtr if the link was successful and NULL otherwise.  In
1247       this case the result is not owned by the  caller  (i.e.  no  ref  count
1248       manipulation  on  either  end  is  needed).  See  the documentation for
1249       Tcl_FSLink for the correct interpretation of the linkAction flags.
1250
1251   LISTVOLUMESPROC
1252       Function to list any  filesystem  volumes  added  by  this  filesystem.
1253       Should  be  implemented only if the filesystem adds volumes at the head
1254       of the filesystem, so that they can be returned by file volumes.
1255
1256              typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
1257
1258       The result should be a list of volumes added  by  this  filesystem,  or
1259       NULL  (or an empty list) if no volumes are provided.  The result object
1260       is considered to be owned by the filesystem (not by  Tcl's  core),  but
1261       should  be  given a refCount for Tcl.  Tcl will use the contents of the
1262       list and then decrement that  refCount.   This  allows  filesystems  to
1263       choose  whether they actually want to retain a “master list” of volumes
1264       or not (if not, they generate the list on the fly and pass  it  to  Tcl
1265       with  a refCount of 1 and then forget about the list, if yes, then they
1266       simply increment the refCount of their master list and pass it  to  Tcl
1267       which will copy the contents and then decrement the count back to where
1268       it was).
1269
1270       Therefore, Tcl considers return values from this proc to be read-only.
1271
1272   FILEATTRSTRINGSPROC
1273       Function to list  all  attribute  strings  which  are  valid  for  this
1274       filesystem.   If  not  implemented  the filesystem will not support the
1275       file attributes command.  This allows arbitrary additional  information
1276       to  be  attached to files in the filesystem.  If it is not implemented,
1277       there is no need to implement the get and set methods.
1278
1279              typedef const char** Tcl_FSFileAttrStringsProc(
1280                      Tcl_Obj *pathPtr,
1281                      Tcl_Obj** objPtrRef);
1282
1283       The called function may either return  an  array  of  strings,  or  may
1284       instead return NULL and place a Tcl list into the given objPtrRef.  Tcl
1285       will take that list and first  increment  its  reference  count  before
1286       using  it.  On completion of that use, Tcl will decrement its reference
1287       count.  Hence if the list should be disposed of by Tcl  when  done,  it
1288       should  have  a  reference count of zero, and if the list should not be
1289       disposed of, the filesystem should ensure it returns an object  with  a
1290       reference count of at least one.
1291
1292   FILEATTRSGETPROC
1293       Function to process a Tcl_FSFileAttrsGet call, used by file attributes.
1294
1295              typedef int Tcl_FSFileAttrsGetProc(
1296                      Tcl_Interp *interp,
1297                      int index,
1298                      Tcl_Obj *pathPtr,
1299                      Tcl_Obj **objPtrRef);
1300
1301       Returns  a  standard  Tcl  return code.  The attribute value retrieved,
1302       which corresponds to the index'th element in the list returned  by  the
1303       Tcl_FSFileAttrStringsProc,  is a Tcl_Obj placed in objPtrRef (if TCL_OK
1304       was returned) and is likely to have a reference count of zero.   Either
1305       way  we  must  either  store  it  somewhere  (e.g.  the Tcl result), or
1306       Incr/Decr its reference count to ensure it is properly freed.
1307
1308   FILEATTRSSETPROC
1309       Function to process a Tcl_FSFileAttrsSet call, used by file attributes.
1310       If the filesystem is read-only, there is no need to implement this.
1311
1312              typedef int Tcl_FSFileAttrsSetProc(
1313                      Tcl_Interp *interp,
1314                      int index,
1315                      Tcl_Obj *pathPtr,
1316                      Tcl_Obj *objPtr);
1317
1318       The attribute value of the index'th element in the list returned by the
1319       Tcl_FSFileAttrStringsProc should be set to the objPtr given.
1320
1321   CREATEDIRECTORYPROC
1322       Function to process a Tcl_FSCreateDirectory  call.   Should  be  imple‐
1323       mented unless the FS is read-only.
1324
1325              typedef int Tcl_FSCreateDirectoryProc(
1326                      Tcl_Obj *pathPtr);
1327
1328       The  return  value is a standard Tcl result indicating whether an error
1329       occurred in the process.  If successful, a new  directory  should  have
1330       been added to the filesystem in the location specified by pathPtr.
1331
1332   REMOVEDIRECTORYPROC
1333       Function  to  process  a  Tcl_FSRemoveDirectory call.  Should be imple‐
1334       mented unless the FS is read-only.
1335
1336              typedef int Tcl_FSRemoveDirectoryProc(
1337                      Tcl_Obj *pathPtr,
1338                      int recursive,
1339                      Tcl_Obj **errorPtr);
1340
1341       The return value is a standard Tcl result indicating whether  an  error
1342       occurred  in  the  process.   If successful, the directory specified by
1343       pathPtr should have been removed from the filesystem.  If the recursive
1344       flag  is  given,  then  a non-empty directory should be deleted without
1345       error.  If this flag is not given, then and the directory is  non-empty
1346       a POSIX “EEXIST” error should be signaled.  If an error does occur, the
1347       name of the file or directory which caused the error should  be  placed
1348       in errorPtr.
1349
1350   DELETEFILEPROC
1351       Function  to  process  a  Tcl_FSDeleteFile call.  Should be implemented
1352       unless the FS is read-only.
1353
1354              typedef int Tcl_FSDeleteFileProc(
1355                      Tcl_Obj *pathPtr);
1356
1357       The return value is a standard Tcl result indicating whether  an  error
1358       occurred  in the process.  If successful, the file specified by pathPtr
1359       should have been removed  from  the  filesystem.   Note  that,  if  the
1360       filesystem  supports symbolic links, Tcl will always call this function
1361       and not Tcl_FSRemoveDirectoryProc when needed to delete them  (even  if
1362       they are symbolic links to directories).
1363

FILESYSTEM EFFICIENCY

1365       These  functions  need  not  be implemented for a particular filesystem
1366       because the core has a  fallback  implementation  available.  See  each
1367       individual description for the consequences of leaving the field NULL.
1368
1369   LSTATPROC
1370       Function  to  process a Tcl_FSLstat call.  If not implemented, Tcl will
1371       attempt to use the statProc defined above instead.  Therefore  it  need
1372       only  be implemented if a filesystem can differentiate between stat and
1373       lstat calls.
1374
1375              typedef int Tcl_FSLstatProc(
1376                      Tcl_Obj *pathPtr,
1377                      Tcl_StatBuf *statPtr);
1378
1379       The  behavior  of  this  function  is  very  similar  to  that  of  the
1380       Tcl_FSStatProc  defined  above,  except that if it is applied to a sym‐
1381       bolic link, it returns information about the link, not about the target
1382       file.
1383
1384   COPYFILEPROC
1385       Function to process a Tcl_FSCopyFile call.  If not implemented Tcl will
1386       fall back on open-r, open-w and fcopy as a copying  mechanism.   There‐
1387       fore  it  need  only  be implemented if the filesystem can perform that
1388       action more efficiently.
1389
1390              typedef int Tcl_FSCopyFileProc(
1391                      Tcl_Obj *srcPathPtr,
1392                      Tcl_Obj *destPathPtr);
1393
1394       The return value is a standard Tcl result indicating whether  an  error
1395       occurred in the copying process.  Note that, destPathPtr is the name of
1396       the file which should become the copy of srcPathPtr. It  is  never  the
1397       name  of  a  directory  into which srcPathPtr could be copied (i.e. the
1398       function is much simpler than the  Tcl  level  file  copy  subcommand).
1399       Note  that,  if the filesystem supports symbolic links, Tcl will always
1400       call this function and not copyDirectoryProc when needed to  copy  them
1401       (even  if  they  are  symbolic  links to directories).  Finally, if the
1402       filesystem determines it cannot support the file copy  action,  calling
1403       Tcl_SetErrno(EXDEV)  and returning a non-TCL_OK result will tell Tcl to
1404       use its standard fallback mechanisms.
1405
1406   RENAMEFILEPROC
1407       Function to process a Tcl_FSRenameFile call.  If not  implemented,  Tcl
1408       will  fall back on a copy and delete mechanism.  Therefore it need only
1409       be implemented if the filesystem can perform  that  action  more  effi‐
1410       ciently.
1411
1412              typedef int Tcl_FSRenameFileProc(
1413                      Tcl_Obj *srcPathPtr,
1414                      Tcl_Obj *destPathPtr);
1415
1416       The  return  value is a standard Tcl result indicating whether an error
1417       occurred in the renaming process.  If the filesystem determines it can‐
1418       not  support  the  file  rename action, calling Tcl_SetErrno(EXDEV) and
1419       returning a non-TCL_OK result will tell Tcl to use its  standard  fall‐
1420       back mechanisms.
1421
1422   COPYDIRECTORYPROC
1423       Function  to  process  a Tcl_FSCopyDirectory call.  If not implemented,
1424       Tcl will fall back on a recursive  file  mkdir,  file  copy  mechanism.
1425       Therefore  it  need  only  be implemented if the filesystem can perform
1426       that action more efficiently.
1427
1428              typedef int Tcl_FSCopyDirectoryProc(
1429                      Tcl_Obj *srcPathPtr,
1430                      Tcl_Obj *destPathPtr,
1431                      Tcl_Obj **errorPtr);
1432
1433       The return value is a standard Tcl result indicating whether  an  error
1434       occurred  in  the copying process.  If an error does occur, the name of
1435       the file or directory which  caused  the  error  should  be  placed  in
1436       errorPtr.  Note  that,  destPathPtr  is  the name of the directory-name
1437       which should become the mirror-image of srcPathPtr. It is not the  name
1438       of  a  directory into which srcPathPtr should be copied (i.e. the func‐
1439       tion is  much  simpler  than  the  Tcl  level  file  copy  subcommand).
1440       Finally,  if  the filesystem determines it cannot support the directory
1441       copy action, calling Tcl_SetErrno(EXDEV)  and  returning  a  non-TCL_OK
1442       result will tell Tcl to use its standard fallback mechanisms.
1443
1444   LOADFILEPROC
1445       Function  to  process  a  Tcl_FSLoadFile call.  If not implemented, Tcl
1446       will fall back on a copy to native-temp followed by a Tcl_FSLoadFile on
1447       that  temporary  copy.   Therefore  it  need only be implemented if the
1448       filesystem can load code directly, or it can be implemented  simply  to
1449       return  TCL_ERROR  to  disable  load  functionality  in this filesystem
1450       entirely.
1451
1452              typedef int Tcl_FSLoadFileProc(
1453                      Tcl_Interp *interp,
1454                      Tcl_Obj *pathPtr,
1455                      Tcl_LoadHandle *handlePtr,
1456                      Tcl_FSUnloadFileProc *unloadProcPtr);
1457
1458       Returns a standard Tcl completion code.  If an error occurs,  an  error
1459       message is left in the interp's result.  The function dynamically loads
1460       a binary code file into memory.  On a successful  load,  the  handlePtr
1461       should  be filled with a token for the dynamically loaded file, and the
1462       unloadProcPtr should be filled in with the address of a procedure.  The
1463       unload  procedure  will  be called with the given Tcl_LoadHandle as its
1464       only parameter when Tcl needs to unload the file.  For example, for the
1465       native  filesystem,  the  Tcl_LoadHandle  returned is currently a token
1466       which can be used in the private TclpFindSymbol to access functions  in
1467       the  new code.  Each filesystem is free to define the Tcl_LoadHandle as
1468       it requires.  Finally, if the filesystem determines it  cannot  support
1469       the  file load action, calling Tcl_SetErrno(EXDEV) and returning a non-
1470       TCL_OK result will tell Tcl to use its standard fallback mechanisms.
1471
1472   UNLOADFILEPROC
1473       Function to unload a previously successfully loaded file.  If load  was
1474       implemented,  then  this  should  also  be implemented, if there is any
1475       cleanup action required.
1476
1477              typedef void Tcl_FSUnloadFileProc(
1478                      Tcl_LoadHandle loadHandle);
1479
1480   GETCWDPROC
1481       Function to process a Tcl_FSGetCwd call.   Most  filesystems  need  not
1482       implement  this.   It  will  usually  only be called once, if getcwd is
1483       called before chdir.  May be NULL.
1484
1485              typedef Tcl_Obj* Tcl_FSGetCwdProc(
1486                      Tcl_Interp *interp);
1487
1488       If the filesystem supports a native notion of a current working  direc‐
1489       tory  (which  might  perhaps  change independent of Tcl), this function
1490       should return that cwd as the result, or NULL if the current  directory
1491       could  not  be determined (e.g. the user does not have appropriate per‐
1492       missions on the cwd directory).  If NULL is returned, an error  message
1493       is left in the interp's result.
1494
1495   CHDIRPROC
1496       Function  to  process a Tcl_FSChdir call.  If filesystems do not imple‐
1497       ment this, it will be emulated by a series of directory access  checks.
1498       Otherwise,  virtual filesystems which do implement it need only respond
1499       with a positive return result if the pathPtr  is  a  valid,  accessible
1500       directory  in  their  filesystem.   They  need not remember the result,
1501       since that will be automatically remembered for  use  by  Tcl_FSGetCwd.
1502       Real  filesystems  should  carry  out the correct action (i.e. call the
1503       correct system chdir API).
1504
1505              typedef int Tcl_FSChdirProc(
1506                      Tcl_Obj *pathPtr);
1507
1508       The Tcl_FSChdirProc changes the applications current working  directory
1509       to  the value specified in pathPtr. The function returns -1 on error or
1510       0 on success.
1511

SEE ALSO

1513       cd(n), file(n), load(n), open(n), pwd(n), unload(n)
1514

KEYWORDS

1516       stat, access, filesystem, vfs, virtual
1517
1518
1519
1520Tcl                                   8.4                        Filesystem(3)
Impressum