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_FSUnloadFile, Tcl_FSMatchInDirec‐
13       tory,   Tcl_FSLink,   Tcl_FSLstat,   Tcl_FSUtime,   Tcl_FSFileAttrsGet,
14       Tcl_FSFileAttrsSet,  Tcl_FSFileAttrStrings,  Tcl_FSStat,  Tcl_FSAccess,
15       Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir,  Tcl_FSPathSeparator,
16       Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalized‐
17       Path, Tcl_FSJoinToPath, Tcl_FSConvertToPathType,  Tcl_FSGetInternalRep,
18       Tcl_FSGetTranslatedPath,   Tcl_FSGetTranslatedStringPath,  Tcl_FSNewNa‐
19       tivePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_GetAccessTime‐
20       FromStat,        Tcl_GetBlockSizeFromStat,       Tcl_GetBlocksFromStat,
21       Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat,  Tcl_GetFSDevice‐
22       FromStat,        Tcl_GetFSInodeFromStat,        Tcl_GetGroupIdFromStat,
23       Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTime‐
24       FromStat,  Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, Tcl_AllocStatBuf
25       - procedures to interact with any filesystem
26

SYNOPSIS

28       #include <tcl.h>
29
30       int
31       Tcl_FSRegister(clientData, fsPtr)
32
33       int
34       Tcl_FSUnregister(fsPtr)
35
36       ClientData
37       Tcl_FSData(fsPtr)
38
39       void
40       Tcl_FSMountsChanged(fsPtr)
41
42       const Tcl_Filesystem *
43       Tcl_FSGetFileSystemForPath(pathPtr)
44
45       Tcl_PathType
46       Tcl_FSGetPathType(pathPtr)
47
48       int
49       Tcl_FSCopyFile(srcPathPtr, destPathPtr)
50
51       int
52       Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)
53
54       int
55       Tcl_FSCreateDirectory(pathPtr)
56
57       int
58       Tcl_FSDeleteFile(pathPtr)
59
60       int
61       Tcl_FSRemoveDirectory(pathPtr, int recursive, errorPtr)
62
63       int
64       Tcl_FSRenameFile(srcPathPtr, destPathPtr)
65
66       Tcl_Obj *
67       Tcl_FSListVolumes(void)
68
69       int
70       Tcl_FSEvalFileEx(interp, pathPtr, encodingName)
71
72       int
73       Tcl_FSEvalFile(interp, pathPtr)
74
75       int
76       Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
77                      loadHandlePtr, unloadProcPtr)
78
79       int                                                                     │
80       Tcl_FSUnloadFile(interp, loadHandle)                                    │
81
82       int
83       Tcl_FSMatchInDirectory(interp, resultPtr, pathPtr, pattern, types)
84
85       Tcl_Obj *
86       Tcl_FSLink(linkNamePtr, toPtr, linkAction)
87
88       int
89       Tcl_FSLstat(pathPtr, statPtr)
90
91       int
92       Tcl_FSUtime(pathPtr, tval)
93
94       int
95       Tcl_FSFileAttrsGet(interp, int index, pathPtr, objPtrRef)
96
97       int
98       Tcl_FSFileAttrsSet(interp, int index, pathPtr, Tcl_Obj *objPtr)
99
100       const char *const *
101       Tcl_FSFileAttrStrings(pathPtr, objPtrRef)
102
103       int
104       Tcl_FSStat(pathPtr, statPtr)
105
106       int
107       Tcl_FSAccess(pathPtr, mode)
108
109       Tcl_Channel
110       Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)
111
112       Tcl_Obj *
113       Tcl_FSGetCwd(interp)
114
115       int
116       Tcl_FSChdir(pathPtr)
117
118       Tcl_Obj *
119       Tcl_FSPathSeparator(pathPtr)
120
121       Tcl_Obj *
122       Tcl_FSJoinPath(listObj, elements)
123
124       Tcl_Obj *
125       Tcl_FSSplitPath(pathPtr, lenPtr)
126
127       int
128       Tcl_FSEqualPaths(firstPtr, secondPtr)
129
130       Tcl_Obj *
131       Tcl_FSGetNormalizedPath(interp, pathPtr)
132
133       Tcl_Obj *
134       Tcl_FSJoinToPath(basePtr, objc, objv)
135
136       int
137       Tcl_FSConvertToPathType(interp, pathPtr)
138
139       ClientData
140       Tcl_FSGetInternalRep(pathPtr, fsPtr)
141
142       Tcl_Obj *
143       Tcl_FSGetTranslatedPath(interp, pathPtr)
144
145       const char *
146       Tcl_FSGetTranslatedStringPath(interp, pathPtr)
147
148       Tcl_Obj *
149       Tcl_FSNewNativePath(fsPtr, clientData)
150
151       const void *
152       Tcl_FSGetNativePath(pathPtr)
153
154       Tcl_Obj *
155       Tcl_FSFileSystemInfo(pathPtr)
156
157       Tcl_StatBuf *
158       Tcl_AllocStatBuf()
159
160       Tcl_WideInt                                                             │
161       Tcl_GetAccessTimeFromStat(statPtr)                                      │
162
163       unsigned                                                                │
164       Tcl_GetBlockSizeFromStat(statPtr)                                       │
165
166       Tcl_WideUInt                                                            │
167       Tcl_GetBlocksFromStat(statPtr)                                          │
168
169       Tcl_WideInt                                                             │
170       Tcl_GetChangeTimeFromStat(statPtr)                                      │
171
172       int                                                                     │
173       Tcl_GetDeviceTypeFromStat(statPtr)                                      │
174
175       unsigned                                                                │
176       Tcl_GetFSDeviceFromStat(statPtr)                                        │
177
178       unsigned                                                                │
179       Tcl_GetFSInodeFromStat(statPtr)                                         │
180
181       int                                                                     │
182       Tcl_GetGroupIdFromStat(statPtr)                                         │
183
184       int                                                                     │
185       Tcl_GetLinkCountFromStat(statPtr)                                       │
186
187       unsigned                                                                │
188       Tcl_GetModeFromStat(statPtr)                                            │
189
190       Tcl_WideInt                                                             │
191       Tcl_GetModificationTimeFromStat(statPtr)                                │
192
193       Tcl_WideUInt                                                            │
194       Tcl_GetSizeFromStat(statPtr)                                            │
195
196       int                                                                     │
197       Tcl_GetUserIdFromStat(statPtr)                                          │
198

ARGUMENTS

200       const Tcl_Filesystem *fsPtr (in)            Points to a structure  con‐
201                                                   taining  the  addresses  of
202                                                   procedures  that   can   be
203                                                   called to perform the vari‐
204                                                   ous filesystem operations.
205
206       Tcl_Obj *pathPtr (in)                       The  path  represented   by
207                                                   this  value is used for the
208                                                   operation in  question.  If
209                                                   the  value does not already
210                                                   have an internal path  rep‐
211                                                   resentation,   it  will  be
212                                                   converted to have one.
213
214       Tcl_Obj *srcPathPtr (in)                    As for  pathPtr,  but  used
215                                                   for  the  source file for a
216                                                   copy or rename operation.
217
218       Tcl_Obj *destPathPtr (in)                   As for  pathPtr,  but  used
219                                                   for  the  destination file‐
220                                                   name for a copy  or  rename
221                                                   operation.
222
223       const char *encodingName (in)               The  encoding  of  the data
224                                                   stored in the file  identi‐
225                                                   fied  by  pathPtr and to be
226                                                   evaluated.
227
228       const char *pattern (in)                    Only files  or  directories
229                                                   matching  this pattern will
230                                                   be returned.
231
232       Tcl_GlobTypeData *types (in)                Only files  or  directories
233                                                   matching  the type descrip‐
234                                                   tions  contained  in   this
235                                                   structure will be returned.
236                                                   This parameter may be NULL.
237
238       Tcl_Interp *interp (in)                     Interpreter to  use  either
239                                                   for results, evaluation, or
240                                                   reporting error messages.
241
242       ClientData clientData (in)                  The native  description  of
243                                                   the path value to create.
244
245       Tcl_Obj *firstPtr (in)                      The  first of two path val‐
246                                                   ues to compare.  The  value
247                                                   may  be  converted  to path
248                                                   type.
249
250       Tcl_Obj *secondPtr (in)                     The second of two path val‐
251                                                   ues  to  compare. The value
252                                                   may be  converted  to  path
253                                                   type.
254
255       Tcl_Obj *listObj (in)                       The  list  of path elements
256                                                   to operate on with  a  join
257                                                   operation.
258
259       int elements (in)                           If non-negative, the number
260                                                   of elements in the  listObj
261                                                   which   should   be  joined
262                                                   together. If negative, then
263                                                   all elements are joined.
264
265       Tcl_Obj **errorPtr (out)                    In  the  case  of an error,
266                                                   filled with  a  value  con‐
267                                                   taining  the  name  of  the
268                                                   file which caused an  error
269                                                   in  the various copy/rename
270                                                   operations.
271
272       Tcl_Obj **objPtrRef (out)                   Filled with  a  value  con‐
273                                                   taining  the  result of the
274                                                   operation.
275
276       Tcl_Obj *resultPtr (out)                    Pre-allocated   value    in
277                                                   which   to   store   (using
278                                                   Tcl_ListObjAppendElement)
279                                                   the list of files or direc‐
280                                                   tories which  are  success‐
281                                                   fully matched.
282
283       int mode (in)                               Mask  consisting  of one or
284                                                   more of  R_OK,  W_OK,  X_OK
285                                                   and  F_OK.  R_OK,  W_OK and
286                                                   X_OK    request    checking
287                                                   whether the file exists and
288                                                   has  read, write and   exe‐
289                                                   cute   permissions, respec‐
290                                                   tively. F_OK just  requests
291                                                   checking  for the existence
292                                                   of the file.
293
294       Tcl_StatBuf *statPtr (out)                  The structure that contains
295                                                   the  result  of  a  stat or
296                                                   lstat operation.
297
298       const char *sym1 (in)                       Name of a procedure to look
299                                                   up in the file's symbol ta‐
300                                                   ble
301
302       const char *sym2 (in)                       Name of a procedure to look
303                                                   up in the file's symbol ta‐
304                                                   ble
305
306       Tcl_PackageInitProc **proc1Ptr (out)        Filled with the init  func‐
307                                                   tion for this code.
308
309       Tcl_PackageInitProc **proc2Ptr (out)        Filled  with  the safe-init
310                                                   function for this code.
311
312       ClientData *clientDataPtr (out)             Filled with the  clientData
313                                                   value   to   pass  to  this
314                                                   code's unload function when
315                                                   it is called.
316
317       Tcl_LoadHandle *loadHandlePtr (out)         Filled   with  an  abstract
318                                                   token   representing    the
319                                                   loaded file.
320
321       Tcl_FSUnloadFileProc **unloadProcPtr (out)  Filled with the function to
322                                                   use to unload this piece of
323                                                   code.
324
325       Tcl_LoadHandle loadHandle (in)              Handle    to   the   loaded
326                                                   library to be unloaded.
327
328       utimbuf *tval (in)                          The access and modification
329                                                   times in this structure are
330                                                   read and used to set  those
331                                                   values for a given file.
332
333       const char *modeString (in)                 Specifies  how  the file is
334                                                   to be  accessed.  May  have
335                                                   any  of  the values allowed
336                                                   for the  mode  argument  to
337                                                   the Tcl open command.
338
339       int permissions (in)                        POSIX-style      permission
340                                                   flags such as  0644.  If  a
341                                                   new  file is created, these
342                                                   permissions will be set  on
343                                                   the created file.
344
345       int *lenPtr (out)                           If  non-NULL,  filled  with
346                                                   the number of  elements  in
347                                                   the split path.
348
349       Tcl_Obj *basePtr (in)                       The  base  path on to which
350                                                   to join the given elements.
351                                                   May be NULL.
352
353       int objc (in)                               The  number  of elements in
354                                                   objv.
355
356       Tcl_Obj *const objv[] (in)                  The elements to join to the
357                                                   given base path.
358
359       Tcl_Obj *linkNamePtr (in)                   The  name of the link to be
360                                                   created or read.
361
362       Tcl_Obj *toPtr (in)                         What   the   link    called
363                                                   linkNamePtr    should    be
364                                                   linked to, or NULL  if  the
365                                                   symbolic  link specified by
366                                                   linkNamePtr is to be read.
367
368       int linkAction (in)                         OR-ed combination of  flags
369                                                   indicating   what  kind  of
370                                                   link  should   be   created
371                                                   (will  be  ignored if toPtr
372                                                   is NULL). Valid bits to set
373                                                   are         TCL_CREATE_SYM‐
374                                                   BOLIC_LINK   and   TCL_CRE‐
375                                                   ATE_HARD_LINK.   When  both
376                                                   flags  are  set   and   the
377                                                   underlying  filesystem  can
378                                                   do either,  symbolic  links
379                                                   are preferred.
380______________________________________________________________________________
381

DESCRIPTION

383       There  are  several  reasons  for  calling  the  Tcl_FS  API  functions
384       (e.g. Tcl_FSAccess and Tcl_FSStat) rather  than  calling  system  level
385       functions  like  access and stat directly. First, they will work cross-
386       platform, so an extension which calls them should  work  unmodified  on
387       Unix  and  Windows. Second, the Windows implementation of some of these
388       functions fixes some bugs in the system level calls. Third, these func‐
389       tion  calls  deal  with  any  “Utf to platform-native” path conversions
390       which may be required (and may cache the results  of  such  conversions
391       for  greater  efficiency on subsequent calls). Fourth, and perhaps most
392       importantly, all of these functions  are  “virtual  filesystem  aware”.
393       Any  virtual  filesystem  (VFS  for  short)  which  has been registered
394       (through Tcl_FSRegister) may reroute file access to  alternative  media
395       or  access  methods. This means that all of these functions (and there‐
396       fore the corresponding file, glob, pwd, cd,  open,  etc. Tcl  commands)
397       may  be  operate  on  “files”  which are not native files in the native
398       filesystem. This also means that any Tcl extension which  accesses  the
399       filesystem  (FS  for  short) through this API is automatically “virtual
400       filesystem aware”.  Of course, if  an  extension  accesses  the  native
401       filesystem directly (through platform-specific APIs, for example), then
402       Tcl cannot intercept such calls.
403
404       If appropriate VFSes have been registered, the “files” may, to give two
405       examples,  be remote (e.g. situated on a remote ftp server) or archived
406       (e.g. lying inside a .zip archive). Such registered filesystems provide
407       a lookup table of functions to implement all or some of the functional‐
408       ity listed here. Finally, the Tcl_FSStat and Tcl_FSLstat calls abstract
409       away  from  what  the  “struct stat” buffer is actually declared to be,
410       allowing the same code to be used both  on  systems  with  and  systems
411       without support for files larger than 2GB in size.
412
413       The  Tcl_FS API is Tcl_Obj-ified and may cache internal representations
414       and other path-related strings (e.g. the  current  working  directory).
415       One side-effect of this is that one must not pass in values with a ref‐
416       erence count of zero to any of these functions. If such calls were han‐
417       dled,  they might result in memory leaks (under some circumstances, the
418       filesystem code may wish to retain a reference to the passed in  value,
419       and  so  one  must not assume that after any of these calls return, the
420       value still has a reference count of zero - it  may  have  been  incre‐
421       mented)  or  in  a  direct  segmentation  fault (or other memory access
422       error) due to the value being freed part way through the complex  value
423       manipulation  required  to ensure that the path is fully normalized and
424       absolute for filesystem determination. The practical  lesson  to  learn
425       from this is that
426
427              Tcl_Obj *path = Tcl_NewStringObj(...);
428              Tcl_FSWhatever(path);
429              Tcl_DecrRefCount(path);
430
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,  values with a reference count of zero are considered not to be
434       valid filesystem paths and calling any Tcl_FS API function with such  a
435       value 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.  Tcl_FSUnload‐ 
493       File reverses the operation, asking for the library  indicated  by  the │
494       loadHandle  to  be removed from the process. Note that, unlike with the │
495       unload command, this does not give the library any opportunity to clean │
496       up.
497
498       Both  the  above functions return a standard Tcl completion code. If an
499       error occurs, an error message is left in the interp's result.
500
501       The token provided via the variable indicated by loadHandlePtr  may  be │
502       used with Tcl_FindSymbol.
503
504       Tcl_FSMatchInDirectory  is used by the globbing code to search a direc‐
505       tory for all files which match a given pattern. The  appropriate  func‐
506       tion for the filesystem to which pathPtr belongs will be called.
507
508       The  return  value is a standard Tcl result indicating whether an error
509       occurred in globbing. Error  messages  are  placed  in  interp  (unless
510       interp  is  NULL, which is allowed), but good results are placed in the
511       resultPtr given.
512
513       Note that the glob code implements recursive  patterns  internally,  so
514       this  function  will  only ever be passed simple patterns, which can be
515       matched using the logic of string match. To handle recursion, Tcl  will
516       call  this  function  frequently  asking  only  for  directories  to be
517       returned. A special case of being called with a NULL pattern  indicates
518       that the path needs to be checked only for the correct type.
519
520       Tcl_FSLink  replaces the library version of readlink, and extends it to
521       support the  creation  of  links.  The  appropriate  function  for  the
522       filesystem to which linkNamePtr belongs will be called.
523
524       If  the toPtr is NULL, a “read link” action is performed. The result is
525       a Tcl_Obj specifying  the  contents  of  the  symbolic  link  given  by
526       linkNamePtr, or NULL if the link could not be read. The result is owned
527       by the caller, which should call Tcl_DecrRefCount when the result is no
528       longer  needed.  If  the toPtr is not NULL, Tcl should create a link of
529       one of the types passed in in the linkAction flag. This flag is an ORed
530       combination   of   TCL_CREATE_SYMBOLIC_LINK  and  TCL_CREATE_HARD_LINK.
531       Where a choice exists (i.e. more than one flag is passed in),  the  Tcl
532       convention  is  to  prefer  symbolic links. When a link is successfully
533       created, the return value should be toPtr (which is  therefore  already
534       owned by the caller). If unsuccessful, NULL is returned.
535
536       Tcl_FSLstat  fills  the  Tcl_StatBuf structure statPtr with information
537       about the specified file. You do not need any access rights to the file
538       to  get  this information but you need search rights to all directories
539       named in the path  leading  to  the  file.  The  Tcl_StatBuf  structure
540       includes  info regarding device, inode (always 0 on Windows), privilege
541       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
542       id  (always 0 on Windows), rdev (same as device on Windows), size, last
543       access time, last modification time, and  last  metadata  change  time.
544       See PORTABLE STAT RESULT API for a description of how to write portable
545       code to allocate and access the Tcl_StatBuf structure.
546
547       If path exists, Tcl_FSLstat returns 0 and the stat structure is  filled
548       with data. Otherwise, -1 is returned, and no stat info is given.
549
550       Tcl_FSUtime replaces the library version of utime.
551
552       This  returns 0 on success and -1 on error (as per the utime documenta‐
553       tion). If successful, the function will update the “atime” and  “mtime”
554       values of the file given.
555
556       Tcl_FSFileAttrsGet   implements  read  access  for  the  hookable  file
557       attributes subcommand. The appropriate function for the  filesystem  to
558       which pathPtr belongs will be called.
559
560       If  the  result  is TCL_OK, then a value was placed in objPtrRef, which
561       will only be temporarily valid (unless Tcl_IncrRefCount is called).
562
563       Tcl_FSFileAttrsSet  implements  write  access  for  the  hookable  file
564       attributes  subcommand.  The appropriate function for the filesystem to
565       which pathPtr belongs will be called.
566
567       Tcl_FSFileAttrStrings implements part of the hookable  file  attributes
568       subcommand.  The appropriate function for the filesystem to which path‐
569       Ptr belongs will be called.
570
571       The called procedure may either return an  array  of  strings,  or  may
572       instead  return NULL and place a Tcl list into the given objPtrRef. Tcl
573       will take that list and first  increment  its  reference  count  before
574       using  it.  On completion of that use, Tcl will decrement its reference
575       count. Hence if the list should be disposed of by  Tcl  when  done,  it
576       should  have  a  reference count of zero, and if the list should not be
577       disposed of, the filesystem should ensure it retains a reference  count
578       to the value.
579
580       Tcl_FSAccess checks whether the process would be allowed to read, write
581       or test for existence of the file (or other  filesystem  object)  whose
582       name  is pathname. If pathname is a symbolic link on Unix, then permis‐
583       sions of the file referred by this symbolic link are tested.
584
585       On success (all requested permissions granted), zero  is  returned.  On
586       error  (at least one bit in mode asked for a permission that is denied,
587       or some other error occurred), -1 is returned.
588
589       Tcl_FSStat fills the Tcl_StatBuf  structure  statPtr  with  information
590       about the specified file. You do not need any access rights to the file
591       to get this information but you need search rights to  all  directories
592       named  in  the  path  leading  to  the  file. The Tcl_StatBuf structure
593       includes info regarding device, inode (always 0 on Windows),  privilege
594       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
595       id (always 0 on Windows), rdev (same as device on Windows), size,  last
596       access  time,  last  modification  time, and last metadata change time.
597       See PORTABLE STAT RESULT API for a description of how to write portable
598       code to allocate and access the Tcl_StatBuf structure.
599
600       If  path  exists, Tcl_FSStat returns 0 and the stat structure is filled
601       with data. Otherwise, -1 is returned, and no stat info is given.
602
603       Tcl_FSOpenFileChannel opens a file specified by pathPtr and  returns  a
604       channel  handle  that  can  be  used to perform input and output on the
605       file. This API is modeled after the fopen procedure of the  Unix  stan‐
606       dard  I/O  library.  The syntax and meaning of all arguments is similar
607       to those given in the Tcl open command when  opening  a  file.   If  an
608       error  occurs  while opening the channel, Tcl_FSOpenFileChannel returns
609       NULL and records  a  POSIX  error  code  that  can  be  retrieved  with
610       Tcl_GetErrno.   In addition, if interp is non-NULL, Tcl_FSOpenFileChan‐
611       nel leaves an error message in interp's result after any error.
612
613       The newly created channel is not  registered  in  the  supplied  inter‐
614       preter;  to  register it, use Tcl_RegisterChannel.  If one of the stan‐
615       dard channels, stdin, stdout or stderr was previously closed,  the  act
616       of  creating  the  new channel also assigns it as a replacement for the
617       standard channel.
618
619       Tcl_FSGetCwd replaces the library version of getcwd.
620
621       It returns the Tcl library's current working  directory.  This  may  be
622       different  to  the  native  platform's working directory, which happens
623       when the current working directory is not in the native filesystem.
624
625       The result is a pointer to a Tcl_Obj specifying the current  directory,
626       or  NULL  if  the current directory could not be determined. If NULL is
627       returned, an error message is left in the interp's result.
628
629       The result already has its reference count incremented for the  caller.
630       When  it  is  no  longer  needed, that reference count should be decre‐
631       mented. This is needed for thread-safety purposes,  to  allow  multiple
632       threads  to  access  this  and  related  functions,  while ensuring the
633       results are always valid.
634
635       Tcl_FSChdir replaces the library version of chdir. The path is  normal‐
636       ized  and  then  passed  to  the  filesystem  which  claims it. If that
637       filesystem does not implement this function, Tcl  will  fallback  to  a
638       combination  of  stat  and access to check whether the directory exists
639       and has appropriate permissions.
640
641       For results, see chdir documentation. If successful, we keep  a  record
642       of   the   successful  path  in  cwdPathPtr  for  subsequent  calls  to
643       Tcl_FSGetCwd.
644
645       Tcl_FSPathSeparator returns the separator character to be used for most
646       specific  element  of the path specified by pathPtr (i.e. the last part
647       of the path).
648
649       The separator is returned as a Tcl_Obj containing a string of length 1.
650       If the path is invalid, NULL is returned.
651
652       Tcl_FSJoinPath  takes  the  given  Tcl_Obj,  which must be a valid list
653       (which is allowed to have a reference count of zero), and  returns  the
654       path  value  given  by considering the first elements elements as valid
655       path segments (each path segment may be a complete path, a partial path
656       or  just a single possible directory or file name). If any path segment
657       is actually an absolute path, then all prior  path  segments  are  dis‐
658       carded.  If elements is less than 0, we use the entire list.
659
660       It  is  possible  that the returned value is actually an element of the
661       given list, so the caller should be careful to increment the  reference
662       count of the result before freeing the list.
663
664       The  returned  value,  typically with a reference count of zero (but it
665       could be shared under some conditions), contains the joined  path.  The
666       caller must add a reference count to the value before using it. In par‐
667       ticular, the returned value could be an element of the given  list,  so
668       freeing the list might free the value prematurely if no reference count
669       has been taken.  If the number of elements is zero, then  the  returned
670       value will be an empty-string Tcl_Obj.
671
672       Tcl_FSSplitPath  takes the given Tcl_Obj, which should be a valid path,
673       and returns a Tcl list value containing each segment of that path as an
674       element.   It  returns  a list value with a reference count of zero. If
675       the passed in lenPtr is non-NULL, the variable it  points  to  will  be
676       updated to contain the number of elements in the returned list.
677
678       Tcl_FSEqualPaths  tests  whether the two paths given represent the same
679       filesystem object.  It returns 1 if the paths are equal, and 0 if  they
680       are different. If either path is NULL, 0 is always returned.
681
682       Tcl_FSGetNormalizedPath  this  important  function  attempts to extract
683       from the given Tcl_Obj a unique normalized path  representation,  whose
684       string value can be used as a unique identifier for the file.
685
686       It returns the normalized path value, owned by Tcl, or NULL if the path
687       was invalid or could otherwise not be successfully converted.   Extrac‐
688       tion  of  absolute,  normalized  paths  is  very efficient (because the
689       filesystem operates on these representations internally), although  the
690       result  when the filesystem contains numerous symbolic links may not be
691       the most user-friendly version of a path. The return value is owned  by
692       Tcl  and  has  a  lifetime  equivalent to that of the pathPtr passed in
693       (unless that is a relative path, in  which  case  the  normalized  path
694       value may be freed any time the cwd changes) - the caller can of course
695       increment the reference count if it  wishes  to  maintain  a  copy  for
696       longer.
697
698       Tcl_FSJoinToPath takes the given value, which should usually be a valid
699       path or NULL, and joins onto it the array of paths segments given.
700
701       Returns a value, typically with reference count of zero (but  it  could
702       be shared under some conditions), containing the joined path. The call‐
703       er must add a reference count to the value before using it. If  any  of
704       the  values passed into this function (pathPtr or path elements) have a
705       reference count of zero, they will be freed when this function returns.
706
707       Tcl_FSConvertToPathType tries to convert the given Tcl_Obj to  a  valid
708       Tcl path type, taking account of the fact that the cwd may have changed
709       even if this value is already supposedly  of  the  correct  type.   The
710       filename may begin with “~” (to indicate current user's home directory)
711       or “~<user>” (to indicate any user's home directory).
712
713       If the conversion succeeds (i.e. the value is a valid path  in  one  of
714       the  current filesystems), then TCL_OK is returned. Otherwise TCL_ERROR
715       is returned, and an error message may be left in the interpreter.
716
717       Tcl_FSGetInternalRep extracts the internal representation  of  a  given
718       path  value,  in  the  given filesystem. If the path value belongs to a
719       different filesystem, we return NULL. If the internal representation is
720       currently  NULL, we attempt to generate it, by calling the filesystem's
721       Tcl_FSCreateInternalRepProc.
722
723       Returns NULL or a valid internal  path  representation.  This  internal
724       representation  is cached, so that repeated calls to this function will
725       not require additional conversions.
726
727       Tcl_FSGetTranslatedPath attempts to extract the  translated  path  from
728       the given Tcl_Obj.
729
730       If  the  translation succeeds (i.e. the value is a valid path), then it
731       is returned. Otherwise NULL will be returned, and an error message  may
732       be  left  in the interpreter. A “translated” path is one which contains
733       no “~” or “~user” sequences (these have been expanded to their  current
734       representation  in  the filesystem). The value returned is owned by the
735       caller, which must store it or call Tcl_DecrRefCount to  ensure  memory
736       is  freed.  This function is of little practical use, and Tcl_FSGetNor‐
737       malizedPath or Tcl_FSGetNativePath are usually better functions to  use
738       for most purposes.
739
740       Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
741       but returns a character string or NULL.  The string returned is dynami‐
742       cally  allocated  and  owned by the caller, which must store it or call
743       ckfree  to  ensure  it  is  freed.  Again,  Tcl_FSGetNormalizedPath  or
744       Tcl_FSGetNativePath  are  usually better functions to use for most pur‐
745       poses.
746
747       Tcl_FSNewNativePath performs something like the reverse  of  the  usual
748       obj->path->nativerep  conversions.  If  some  code  retrieves a path in
749       native form (from, e.g. readlink or a native dialog), and that path  is
750       to be used at the Tcl level, then calling this function is an efficient
751       way of creating the appropriate path value type.
752
753       The resulting value is a pure “path” value, which will only  receive  a
754       UTF-8 string representation if that is required by some Tcl code.
755
756       Tcl_FSGetNativePath  is  for use by the Win/Unix native filesystems, so
757       that they can easily retrieve the native (char* or TCHAR*)  representa‐
758       tion  of  a  path.  This  function  is  a  convenience  wrapper  around
759       Tcl_FSGetInternalRep. It may be desirable in the future  to  have  non-
760       string-based  native  representations (for example, on MacOSX, a repre‐
761       sentation using a fileSpec of FSRef structure would  probably  be  more
762       efficient).  On  Windows  a full Unicode representation would allow for
763       paths of unlimited length. Currently the  representation  is  simply  a
764       character  string  which may contain either the relative path or a com‐
765       plete, absolute normalized path in the native encoding (complex  condi‐
766       tions dictate which of these will be provided, so neither can be relied
767       upon, unless the path is known to be absolute). If you  need  a  native
768       path which must be absolute, then you should ask for the native version
769       of a normalized path. If for some reason a non-absolute, non-normalized
770       version  of  the  path  is  needed, that must be constructed separately
771       (e.g. using Tcl_FSGetTranslatedPath).
772
773       The native representation is cached so  that  repeated  calls  to  this
774       function  will  not require additional conversions. The return value is
775       owned by Tcl and has a lifetime  equivalent  to  that  of  the  pathPtr
776       passed  in  (unless  that  is a relative path, in which case the native
777       representation may be freed any time the cwd changes).
778
779       Tcl_FSFileSystemInfo returns a list of two elements. The first  element
780       is  the  name  of  the  filesystem  (e.g.   “native”,  “vfs”, “zip”, or
781       “prowrap”, perhaps), and the second is the particular type of the given
782       path within that filesystem (which is filesystem dependent). The second
783       element may be empty if the filesystem does not provide a further cate‐
784       gorization of files.
785
786       A  valid  list  value  is returned, unless the path value is not recog‐
787       nized, when NULL will be returned.
788
789       Tcl_FSGetFileSystemForPath returns  a  pointer  to  the  Tcl_Filesystem
790       which accepts this path as valid.
791
792       If no filesystem will accept the path, NULL is returned.
793
794       Tcl_FSGetPathType  determines whether the given path is relative to the
795       current directory, relative to the current volume, or absolute.
796
797       It   returns   one   of   TCL_PATH_ABSOLUTE,   TCL_PATH_RELATIVE,    or
798       TCL_PATH_VOLUME_RELATIVE
799
800   PORTABLE STAT RESULT API
801       Tcl_AllocStatBuf  allocates a Tcl_StatBuf on the system heap (which may
802       be deallocated by being passed to ckfree). This  allows  extensions  to
803       invoke  Tcl_FSStat  and Tcl_FSLstat without being dependent on the size
804       of the buffer. That in turn depends on the flags used to build Tcl.
805
806       The portable fields of a Tcl_StatBuf may be read  using  the  following │
807       functions,  each  of which returns the value of the corresponding field │
808       listed in the table below. Note that on some  platforms  there  may  be │
809       other fields in the Tcl_StatBuf as it is an alias for a suitable system │
810       structure, but only the portable ones are made available here. See your │
811       system documentation for a full description of these fields.            │
812
813              Access Function                    Field
814               Tcl_GetFSDeviceFromStat            st_dev                       │
815               Tcl_GetFSInodeFromStat             st_ino                       │
816               Tcl_GetModeFromStat                st_mode                      │
817               Tcl_GetLinkCountFromStat           st_nlink                     │
818               Tcl_GetUserIdFromStat              st_uid                       │
819               Tcl_GetGroupIdFromStat             st_gid                       │
820               Tcl_GetDeviceTypeFromStat          st_rdev                      │
821               Tcl_GetAccessTimeFromStat          st_atime                     │
822               Tcl_GetModificationTimeFromStat    st_mtime                     │
823               Tcl_GetChangeTimeFromStat          st_ctime                     │
824               Tcl_GetSizeFromStat                st_size                      │
825               Tcl_GetBlocksFromStat              st_blocks                    │
826               Tcl_GetBlockSizeFromStat           st_blksize                   │
827
828

THE VIRTUAL FILESYSTEM API

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

FILESYSTEM INFRASTRUCTURE

979       These  fields  contain basic information about the filesystem structure
980       and addresses of functions which are used  to  associate  a  particular
981       filesystem  with  a  file  path, and deal with the internal handling of
982       path representations, for example copying and freeing such  representa‐
983       tions.
984
985   TYPENAME
986       The  typeName  field  contains a null-terminated string that identifies
987       the type of the filesystem implemented, e.g.  “native”, “zip” or “vfs”.
988
989   STRUCTURE LENGTH
990       The    structureLength    field    is    generally    implemented    as
991       sizeof(Tcl_Filesystem),  and  is there to allow easier binary backwards
992       compatibility if the size of the structure  changes  in  a  future  Tcl
993       release.
994
995   VERSION
996       The version field should be set to TCL_FILESYSTEM_VERSION_1.
997
998   PATHINFILESYSTEMPROC
999       The pathInFilesystemProc field contains the address of a function which
1000       is called to determine whether a  given  path  value  belongs  to  this
1001       filesystem  or not. Tcl will only call the rest of the filesystem func‐
1002       tions with a path for which this function has returned TCL_OK.  If  the
1003       path  does  not  belong, -1 should be returned (the behavior of Tcl for
1004       any other return value is not defined). If TCL_OK is returned, then the
1005       optional clientDataPtr output parameter can be used to return an inter‐
1006       nal (filesystem specific) representation of the  path,  which  will  be
1007       cached  inside  the path value, and may be retrieved efficiently by the
1008       other filesystem functions. Tcl will simultaneously cache the fact that
1009       this  path belongs to this filesystem. Such caches are invalidated when
1010       filesystem structures are added or removed from Tcl's internal list  of
1011       known filesystems.
1012
1013              typedef int Tcl_FSPathInFilesystemProc(
1014                      Tcl_Obj *pathPtr,
1015                      ClientData *clientDataPtr);
1016
1017   DUPINTERNALREPPROC
1018       This  function makes a copy of a path's internal representation, and is
1019       called when Tcl needs to duplicate a path value. If NULL, Tcl will sim‐
1020       ply  not  copy  the  internal representation, which may then need to be
1021       regenerated later.
1022
1023              typedef ClientData Tcl_FSDupInternalRepProc(
1024                      ClientData clientData);
1025
1026   FREEINTERNALREPPROC
1027       Free the internal representation. This must be implemented if  internal
1028       representations  need freeing (i.e. if some memory is allocated when an
1029       internal representation is generated), but may otherwise be NULL.
1030
1031              typedef void Tcl_FSFreeInternalRepProc(
1032                      ClientData clientData);
1033
1034   INTERNALTONORMALIZEDPROC
1035       Function to convert internal representation to a normalized path.  Only
1036       required if the filesystem creates pure path values with no string/path
1037       representation. The return value is a Tcl value whose string  represen‐
1038       tation is the normalized path.
1039
1040              typedef Tcl_Obj *Tcl_FSInternalToNormalizedProc(
1041                      ClientData clientData);
1042
1043   CREATEINTERNALREPPROC
1044       Function to take a path value, and calculate an internal representation
1045       for it, and store that native representation in the value. May be  NULL
1046       if  paths  have  no  internal  representation,  or if the Tcl_FSPathIn‐
1047       FilesystemProc for this filesystem always immediately creates an inter‐
1048       nal representation for paths it accepts.
1049
1050              typedef ClientData Tcl_FSCreateInternalRepProc(
1051                      Tcl_Obj *pathPtr);
1052
1053   NORMALIZEPATHPROC
1054       Function to normalize a path. Should be implemented for all filesystems
1055       which can have multiple string representations for the same path value.
1056       In Tcl, every “path” must have a single unique “normalized” string rep‐
1057       resentation. Depending on the filesystem, there may be  more  than  one
1058       unnormalized  string  representation  which refers to that path (e.g. a
1059       relative path, a path with different character case if  the  filesystem
1060       is  case  insensitive,  a  path contain a reference to a home directory
1061       such as “~”, a path containing symbolic links, etc). If the  very  last
1062       component  in  the  path is a symbolic link, it should not be converted
1063       into the value it points to (but its case or other  aspects  should  be
1064       made  unique).  All other path components should be converted from sym‐
1065       bolic links. This one exception is required to agree with Tcl's  seman‐
1066       tics  with  file  delete,  file rename, file copy operating on symbolic
1067       links.  This function may be called with nextCheckpoint either  at  the
1068       beginning  of  the  path (i.e. zero), at the end of the path, or at any
1069       intermediate file separator in the path. It will  never  point  to  any
1070       other  arbitrary  position  in the path. In the last of the three valid
1071       cases, the implementation can assume that the path up to and  including
1072       the file separator is known and normalized.
1073
1074              typedef int Tcl_FSNormalizePathProc(
1075                      Tcl_Interp *interp,
1076                      Tcl_Obj *pathPtr,
1077                      int nextCheckpoint);
1078

FILESYSTEM OPERATIONS

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

FILESYSTEM EFFICIENCY

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

SEE ALSO

1545       cd(n),  file(n),  filename(n),  load(n),  open(n),  pwd(n),  source(n),
1546       unload(n)
1547

KEYWORDS

1549       stat, access, filesystem, vfs, virtual filesystem
1550
1551
1552
1553Tcl                                   8.4                        Filesystem(3)
Impressum