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_FSLoadFile,    Tcl_FSMatchInDirectory,   Tcl_FSLink,   Tcl_FSLstat,
13       Tcl_FSUtime,  Tcl_FSFileAttrsGet,   Tcl_FSFileAttrsSet,   Tcl_FSFileAt‐
14       trStrings,     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(pathObjPtr)
39
40       Tcl_PathType
41       Tcl_FSGetPathType(pathObjPtr)
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_FSEvalFile(interp, pathPtr)
66
67       int
68       Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
69                      handlePtr, unloadProcPtr)
70
71       int
72       Tcl_FSMatchInDirectory(interp, result, pathPtr, pattern, types)
73
74       Tcl_Obj*
75       Tcl_FSLink(linkNamePtr, toPtr, linkAction)
76
77       int
78       Tcl_FSLstat(pathPtr, statPtr)
79
80       int
81       Tcl_FSUtime(pathPtr, tval)
82
83       int
84       Tcl_FSFileAttrsGet(interp, int index, pathPtr, objPtrRef)
85
86       int
87       Tcl_FSFileAttrsSet(interp, int index, pathPtr, Tcl_Obj *objPtr)
88
89       CONST char**
90       Tcl_FSFileAttrStrings(pathPtr, objPtrRef)
91
92       int
93       Tcl_FSStat(pathPtr, statPtr)
94
95       int
96       Tcl_FSAccess(pathPtr, mode)
97
98       Tcl_Channel
99       Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)
100
101       Tcl_Obj*
102       Tcl_FSGetCwd(interp)
103
104       int
105       Tcl_FSChdir(pathPtr)
106
107       Tcl_Obj*
108       Tcl_FSPathSeparator(pathPtr)
109
110       Tcl_Obj*
111       Tcl_FSJoinPath(listObj, elements)
112
113       Tcl_Obj*
114       Tcl_FSSplitPath(pathPtr, lenPtr)
115
116       int
117       Tcl_FSEqualPaths(firstPtr, secondPtr)
118
119       Tcl_Obj*
120       Tcl_FSGetNormalizedPath(interp, pathPtr)
121
122       Tcl_Obj*
123       Tcl_FSJoinToPath(basePtr, objc, objv)
124
125       int
126       Tcl_FSConvertToPathType(interp, pathPtr)
127
128       ClientData
129       Tcl_FSGetInternalRep(pathPtr, fsPtr)
130
131       Tcl_Obj*
132       Tcl_FSGetTranslatedPath(interp, pathPtr)
133
134       CONST char*
135       Tcl_FSGetTranslatedStringPath(interp, pathPtr)
136
137       Tcl_Obj*
138       Tcl_FSNewNativePath(fsPtr, clientData)
139
140       CONST char*
141       Tcl_FSGetNativePath(pathPtr)
142
143       Tcl_Obj*
144       Tcl_FSFileSystemInfo(pathPtr)
145
146       Tcl_StatBuf*
147       Tcl_AllocStatBuf()
148

ARGUMENTS

150       Tcl_Filesystem   *fsPtr   (in)      Points  to  a  structure containing
151                                           the addresses  of  procedures  that
152                                           can  be called to perform the vari‐
153                                           ous filesystem operations.
154
155       Tcl_Obj          *pathPtr (in)      The path represented by this object
156                                           is  used for the operation in ques‐
157                                           tion.   If  the  object  does   not
158                                           already  have an internal path rep‐
159                                           resentation, it will  be  converted
160                                           to have one.
161
162       Tcl_Obj          *srcPathPtr(in)    As  for  pathPtr,  but used for the
163                                           source file for a  copy  or  rename
164                                           operation.
165
166       Tcl_Obj          *destPathPtr(in)   As  for  pathPtr,  but used for the
167                                           destination filename for a copy  or
168                                           rename operation.
169
170       CONST char       *pattern (in)      Only  files or directories matching
171                                           this pattern will  be  returned  by
172                                           Tcl_FSMatchInDirectory.
173
174       GlobTypeData     *types   (in)      Only  files or directories matching
175                                           the type descriptions contained  in
176                                           this  structure will be returned by
177                                           Tcl_FSMatchInDirectory.  It is very
178                                           important that the 'directory' flag
179                                           is properly handled.  This  parame‐
180                                           ter may be NULL.
181
182       Tcl_Interp       *interp  (in)      Interpreter   to   use  either  for
183                                           results, evaluation,  or  reporting
184                                           error messages.
185
186       ClientData       clientData(in)     The  native description of the path
187                                           object to create.
188
189       Tcl_Obj          *firstPtr(in)      The first of two  path  objects  to
190                                           compare.   The  object  may be con‐
191                                           verted to path type.
192
193       Tcl_Obj          *secondPtr(in)     The second of two path  objects  to
194                                           compare.   The  object  may be con‐
195                                           verted to path type.
196
197       Tcl_Obj          *listObj (in)      The list of path elements to  oper‐
198                                           ate on with a join operation.
199
200       int              elements (in)      If non-negative, the number of ele‐
201                                           ments in the listObj  which  should
202                                           be  joined  together.  If negative,
203                                           then all elements are joined.
204
205       Tcl_Obj          **errorPtr(out)    In the case  of  an  error,  filled
206                                           with  an object containing the name
207                                           of the file which caused  an  error
208                                           in  the  various copy/rename opera‐
209                                           tions.
210
211       Tcl_Obj          **objPtrRef(out)   Filled with  an  object  containing
212                                           the result of the operation.
213
214       Tcl_Obj          *result  (out)     Pre-allocated  object  in  which to
215                                           store (by lappending) the  list  of
216                                           files or directories which are suc‐
217                                           cessfully        matched         in
218                                           Tcl_FSMatchInDirectory.
219
220       int              mode     (in)      Mask  consisting  of one or more of
221                                           R_OK, W_OK, X_OK and  F_OK.   R_OK,
222                                           W_OK   and  X_OK  request  checking
223                                           whether the file  exists  and   has
224                                           read,  write  and  execute  permis‐
225                                           sions,  respectively.   F_OK   just
226                                           requests checking for the existence
227                                           of the file.
228
229       Tcl_StatBuf      *statPtr (out)     The  structure  that  contains  the
230                                           result  of  a  stat or lstat opera‐
231                                           tion.
232
233       CONST char       *sym1    (in)      Name of a procedure to look  up  in
234                                           the file's symbol table
235
236       CONST char       *sym2    (in)      Name  of  a procedure to look up in
237                                           the file's symbol table
238
239       Tcl_PackageInitProc       **proc1Ptr(out)
240                                           Filled with the init  function  for
241                                           this code.
242
243       Tcl_PackageInitProc       **proc2Ptr(out)
244                                           Filled  with the safe-init function
245                                           for this code.
246
247       Tcl_LoadHandle   *handlePtr(out)    Filled with an abstract token  rep‐
248                                           resenting the loaded file.
249
250       ClientData       *clientDataPtr(out)
251                                           Filled with the clientData value to
252                                           pass to this code's unload function
253                                           when it is called.
254
255       TclfsUnloadFileProc_      **unloadProcPtr(out)
256                                           Filled  with the function to use to
257                                           unload this piece of code.
258
259       utimbuf          *tval    (in)      The access and  modification  times
260                                           in this structure are read and used
261                                           to set those  values  for  a  given
262                                           file.
263
264       CONST char       *modeString(in)    Specifies  how  the  file  is to be
265                                           accessed.  May have any of the val‐
266                                           ues  allowed  for the mode argument
267                                           to the Tcl open command.
268
269       int              permissions(in)    POSIX-style permission  flags  such
270                                           as 0644.  If a new file is created,
271                                           these permissions will  be  set  on
272                                           the created file.
273
274       int              *lenPtr  (out)     If non-NULL, filled with the number
275                                           of elements in the split path.
276
277       Tcl_Obj          *basePtr (in)      The base path on to which  to  join
278                                           the given elements.  May be NULL.
279
280       int              objc     (in)      The number of elements in objv.
281
282       Tcl_Obj *CONST   objv[]   (in)      The  elements  to join to the given
283                                           base path.
284_________________________________________________________________
285
286

DESCRIPTION

288       There are several reasons for calling the  Tcl_FS...  functions  rather
289       than  calling  system  level  functions  like access and stat directly.
290       First, they will work cross-platform, so an extension which calls  them
291       should work unmodified on Unix, MacOS and Windows.  Second, the Windows
292       implementation of some of these functions fixes some bugs in the system
293       level  calls.   Third, these function calls deal with any 'Utf to plat‐
294       form-native' path conversions which may be required (and may cache  the
295       results  of  such  conversions  for  greater  efficiency  on subsequent
296       calls).  Fourth, and perhaps most importantly, all of  these  functions
297       are  'virtual filesystem aware'.  Any virtual filesystem which has been
298       registered (through Tcl_FSRegister) may reroute file access to alterna‐
299       tive  media  or access methods.  This means that all of these functions
300       (and therefore the corresponding file, glob, pwd, cd, open,  etc.   Tcl
301       commands)  may  be operate on 'files' which are not native files in the
302       native filesystem.  This  also  means  that  any  Tcl  extension  which
303       accesses  the  filesystem  through  this  API is automatically 'virtual
304       filesystem aware'.  Of course, if  an  extension  accesses  the  native
305       filesystem directly (through platform-specific APIs, for example), then
306       Tcl cannot intercept such calls.
307
308       If appropriate vfs's have been registered, the 'files' may, to give two
309       examples,  be remote (e.g. situated on a remote ftp server) or archived
310       (e.g. lying inside a .zip archive).  Such registered  filesystems  pro‐
311       vide  a lookup table of functions to implement all or some of the func‐
312       tionality listed here.  Finally, the Tcl_FSStat and  Tcl_FSLstat  calls
313       abstract  away  from  what  the 'struct stat' buffer buffer is actually
314       declared to be, allowing the same code to be used both on systems  with
315       and systems without support for files larger than 2GB in size.
316
317       The  Tcl_FS...  are  objectified and may cache internal representations
318       and other path-related strings (e.g. the  current  working  directory).
319       One  side-effect  of  this  is that one must not pass in objects with a
320       refCount of zero to any of these functions.  If such  calls  were  han‐
321       dled,  they might result in memory leaks (under some circumstances, the
322       filesystem code may wish to retain a reference to the passed in object,
323       and  so  one  must not assume that after any of these calls return, the
324       object still has a refCount of zero - it may have been incremented), or
325       in a direct segfault due to the object being freed part way through the
326       complex object manipulation required to ensure that the path  is  fully
327       normalized  and  absolute  for filesystem determination.  The practical
328       lesson to learn from this is that Tcl_Obj *path = Tcl_NewStringObj(...)
329       ;  Tcl_FS...(path) ; Tcl_DecrRefCount(path) is wrong, and may segfault.
330       The 'path' must have its refCount incremented before passing it in,  or
331       decrementing  it.  For this reason, objects with a refCount of zero are
332       considered not to be valid filesystem paths and calling any Tcl_FS  API
333       with such an object will result in no action being taken.
334
335       Tcl_FSCopyFile  attempts  to  copy  the file given by srcPathPtr to the
336       path name given by destPathPtr.  If the two paths given lie in the same
337       filesystem (according to Tcl_FSGetFileSystemForPath) then that filesys‐
338       tem's 'copy file' function is called (if it  is  non-NULL).   Otherwise
339       the function returns -1 and sets Tcl's errno to the 'EXDEV' posix error
340       code (which signifies a 'cross-domain link').
341
342       Tcl_FSCopyDirectory attempts to copy the directory given by  srcPathPtr
343       to  the  path name given by destPathPtr.  If the two paths given lie in
344       the same filesystem (according to Tcl_FSGetFileSystemForPath) then that
345       filesystem's  'copy file' function is called (if it is non-NULL).  Oth‐
346       erwise the function returns -1 and sets  Tcl's  errno  to  the  'EXDEV'
347       posix error code (which signifies a 'cross-domain link').
348
349       Tcl_FSCreateDirectory attempts to create the directory given by pathPtr
350       by calling the owning filesystem's 'create directory' function.
351
352       Tcl_FSDeleteFile attempts to delete the file given by pathPtr by  call‐
353       ing the owning filesystem's 'delete file' function.
354
355       Tcl_FSRemoveDirectory attempts to remove the directory given by pathPtr
356       by calling the owning filesystem's 'remove directory' function.
357
358       Tcl_FSRenameFile attempts to rename the file or directory given by src‐
359       PathPtr  to the path name given by destPathPtr.  If the two paths given
360       lie in the same filesystem  (according  to  Tcl_FSGetFileSystemForPath)
361       then  that filesystem's 'rename file' function is called (if it is non-
362       NULL).  Otherwise the function returns -1 and sets Tcl's errno  to  the
363       'EXDEV' posix error code (which signifies a ``cross-domain link'').
364
365       Tcl_FSListVolumes calls each filesystem which has a non-NULL 'list vol‐
366       umes' function and asks them to return their list of root volumes.   It
367       accumulates the return values in a list which is returned to the caller
368       (with a refCount of 0).
369
370       Tcl_FSEvalFile reads the file given by pathPtr and evaluates  its  con‐
371       tents  as a Tcl script.  It returns the same information as Tcl_EvalOb‐
372       jEx.  If the file couldn't be read then a  Tcl  error  is  returned  to
373       describe why the file couldn't be read.  The eofchar for files is '\32'
374       (^Z) for all platforms.  If you require a ``^Z''  in  code  for  string
375       comparison,  you  can  use ``\032'' or ``\u001a'', which will be safely
376       substituted by the Tcl interpreter into ``^Z''.
377
378       Tcl_FSLoadFile dynamically loads a binary code  file  into  memory  and
379       returns  the  addresses of two procedures within that file, if they are
380       defined.  The appropriate function for the filesystem to which  pathPtr
381       belongs  will  be  called.   If that filesystem does not implement this
382       function (most virtual filesystems will not, because of OS  limitations
383       in  dynamically loading binary code), Tcl will attempt to copy the file
384       to a temporary directory and load that temporary file.
385
386       Returns a standard Tcl completion code.  If an error occurs,  an  error
387       message is left in the interp's result.
388
389       Tcl_FSMatchInDirectory  is used by the globbing code to search a direc‐
390       tory for all files which match a given pattern.  The appropriate  func‐
391       tion for the filesystem to which pathPtr belongs will be called.
392
393       The  return  value is a standard Tcl result indicating whether an error
394       occurred in globbing.  Error messages are placed in  interp,  but  good
395       results are placed in the resultPtr given.
396                          Note  that the 'glob' code implements recursive pat‐
397       terns internally, so this function will only ever be passed simple pat‐
398       terns, which can be matched using the logic of 'string match'.  To han‐
399       dle recursion, Tcl will call this function frequently asking  only  for
400       directories to be returned.
401
402       Tcl_FSLink  replaces  the library version of readlink(), and extends it
403       to support the creation of links.  The  appropriate  function  for  the
404       filesystem to which linkNamePtr belongs will be called.
405
406       If  the toPtr is NULL, a readlink action is performed.  The result is a
407       Tcl_Obj  specifying  the  contents  of  the  symbolic  link  given   by
408       linkNamePtr,  or  NULL  if  the  link could not be read.  The result is
409       owned by the caller, which should call Tcl_DecrRefCount when the result
410       is  no  longer  needed.   If the toPtr is not NULL, Tcl should create a
411       link of one of the types passed in in the linkAction flag.   This  flag
412       is   an  or'd  combination  of  TCL_CREATE_SYMBOLIC_LINK  and  TCL_CRE‐
413       ATE_HARD_LINK.  Where a choice exists  (i.e.  more  than  one  flag  is
414       passed  in),  the  Tcl  convention is to prefer symbolic links.  When a
415       link is successfully created, the return value should be  toPtr  (which
416       is  therefore  already  owned  by  the  caller).  If unsuccessful, NULL
417       should be returned.
418
419       Tcl_FSLstat fills the stat structure statPtr with information about the
420       specified  file.   You do not need any access rights to the file to get
421       this information but you need search rights to all directories named in
422       the path leading to the file.  The stat structure includes info regard‐
423       ing device, inode (always 0 on Windows), privilege mode, nlink  (always
424       1  on  Windows),  user  id (always 0 on Windows), group id (always 0 on
425       Windows), rdev (same as device on Windows),  size,  last  access  time,
426       last modification time, and creation time.
427
428       If  path exists, Tcl_FSLstat returns 0 and the stat structure is filled
429       with data.  Otherwise, -1 is returned, and no stat info is given.
430
431       Tcl_FSUtime replaces the library version of utime.
432
433       For results see 'utime' documentation.   If  successful,  the  function
434       will update the 'atime' and 'mtime' values of the file given.
435
436       Tcl_FSFileAttrsGet  implements  read  access  for  the  hookable  'file
437       attributes' subcommand.  The appropriate function for the filesystem to
438       which pathPtr belongs will be called.
439
440       If  the result is TCL_OK, then an object was placed in objPtrRef, which
441       will only be temporarily valid (unless Tcl_IncrRefCount is called).
442
443       Tcl_FSFileAttrsSet implements  write  access  for  the  hookable  'file
444       attributes' subcommand.  The appropriate function for the filesystem to
445       which pathPtr belongs will be called.
446
447       Tcl_FSFileAttrStrings implements part of the hookable 'file attributes'
448       subcommand.  The appropriate function for the filesystem to which path‐
449       Ptr belongs will be called.
450
451       The called procedure may either return an  array  of  strings,  or  may
452       instead return NULL and place a Tcl list into the given objPtrRef.  Tcl
453       will take that list and first increment its refCount before  using  it.
454       On  completion  of that use, Tcl will decrement its refCount.  Hence if
455       the list should be disposed of by Tcl when done, it should have a  ref‐
456       Count  of zero, and if the list should not be disposed of, the filesys‐
457       tem should ensure it retains a refCount on the object.
458
459       Tcl_FSAccess checks whether the process would be allowed to read, write
460       or  test  for existence of the file (or other file system object) whose
461       name is pathname.   If pathname is a symbolic link on Unix,  then  per‐
462       missions of the file referred by this symbolic link are tested.
463
464       On  success  (all requested permissions granted), zero is returned.  On
465       error (at least one bit in mode asked for a permission that is  denied,
466       or some other  error occurred), -1 is returned.
467
468       Tcl_FSStat  fills the stat structure statPtr with information about the
469       specified file.  You do not need any access rights to the file  to  get
470       this information but you need search rights to all directories named in
471       the path leading to the file.  The stat structure includes info regard‐
472       ing  device, inode (always 0 on Windows), privilege mode, nlink (always
473       1 on Windows), user id (always 0 on Windows), group  id  (always  0  on
474       Windows),  rdev  (same  as  device on Windows), size, last access time,
475       last modification time, and creation time.
476
477       If path exists, Tcl_FSStat returns 0 and the stat structure  is  filled
478       with data.  Otherwise, -1 is returned, and no stat info is given.
479
480       Tcl_FSOpenFileChannel  opens  a file specified by pathPtr and returns a
481       channel handle that can be used to perform  input  and  output  on  the
482       file.  This  API is modeled after the fopen procedure of the Unix stan‐
483       dard I/O library.  The syntax and meaning of all arguments  is  similar
484       to  those  given  in  the  Tcl open command when opening a file.  If an
485       error occurs while opening the channel,  Tcl_FSOpenFileChannel  returns
486       NULL  and  records  a  POSIX  error  code  that  can  be retrieved with
487       Tcl_GetErrno.  In addition, if interp is non-NULL,  Tcl_FSOpenFileChan‐
488       nel leaves an error message in interp's result after any error.
489
490       The  newly  created  channel  is  not registered in the supplied inter‐
491       preter; to register it, use Tcl_RegisterChannel, described  below.   If
492       one  of  the  standard channels, stdin, stdout or stderr was previously
493       closed, the act of creating the  new  channel  also  assigns  it  as  a
494       replacement for the standard channel.
495
496       Tcl_FSGetCwd replaces the library version of getcwd().
497
498       It  returns  the  Tcl library's current working directory.  This may be
499       different to the native platform's working directory, in the  case  for
500       which the cwd is not in the native filesystem.
501
502       The  result is a pointer to a Tcl_Obj specifying the current directory,
503       or NULL if the current directory could not be determined.  If  NULL  is
504       returned,   an   error   message   is  left  in  the  interp's  result.
505                         The result already has its refCount  incremented  for
506       the  caller.   When  it  is  no  longer needed, that refCount should be
507       decremented.  This is needed for thread-safety purposes, to allow  mul‐
508       tiple  threads to access this and related functions, while ensuring the
509       results are always valid.
510
511       Tcl_FSChdir replaces the library version of chdir().  The path is  nor‐
512       malized  and  then  passed  to the filesystem which claims it.  If that
513       filesystem does not implement this function, Tcl  will  fallback  to  a
514       combination  of  stat  and access to check whether the directory exists
515       and has appropriate permissions.
516
517       For results, see chdir()  documentation.   If  successful,  we  keep  a
518       record  of  the  successful  path in cwdPathPtr for subsequent calls to
519       getcwd.
520
521       Tcl_FSPathSeparator returns the separator character to be used for most
522       specific  element  of the path specified by pathPtr (i.e. the last part
523       of the path).
524
525       The separator is returned as a Tcl_Obj containing a string of length 1.
526       If the path is invalid, NULL is returned.
527
528       Tcl_FSJoinPath  takes  the given Tcl_Obj, which should be a valid list,
529       and returns the path object given by considering the  first  'elements'
530       elements  as  valid  path segments.  If elements < 0, we use the entire
531       list.
532
533       Returns object with refCount of zero, containing the joined path.
534
535       Tcl_FSSplitPath takes the given Tcl_Obj, which should be a valid  path,
536       and  returns  a Tcl List object containing each segment of that path as
537       an element.
538
539       Returns list object with refCount of zero.  If the passed in lenPtr  is
540       non-NULL,  we  use  it to return the number of elements in the returned
541       list.
542
543       Tcl_FSEqualPaths tests whether the two paths given represent  the  same
544       filesystem object
545
546       It  returns  1 if the paths are equal, and 0 if they are different.  If
547       either path is NULL, 0 is always returned.
548
549       Tcl_FSGetNormalizedPath this important  function  attempts  to  extract
550       from  the  given Tcl_Obj a unique normalized path representation, whose
551       string value can be used as a unique identifier for the file.
552
553       It returns the normalized path object, with refCount of zero,  or  NULL
554       if  the  path  was  invalid or could otherwise not be successfully con‐
555       verted.  Extraction of absolute, normalized  paths  is  very  efficient
556       (because  the filesystem operates on these representations internally),
557       although the result when  the  filesystem  contains  numerous  symbolic
558       links may not be the most user-friendly version of a path.
559
560       Tcl_FSJoinToPath  takes  the  given  object,  which should usually be a
561       valid path or NULL, and joins onto  it  the  array  of  paths  segments
562       given.
563
564       Returns object with refCount of zero, containing the joined path.
565
566       Tcl_FSConvertToPathType  tries  to convert the given Tcl_Obj to a valid
567       Tcl path type, taking account of the fact that the cwd may have changed
568       even  if  this  object  is already supposedly of the correct type.  The
569       filename may begin with "~" (to indicate current user's home directory)
570       or "~<user>" (to indicate any user's home directory).
571
572       If  the  conversion succeeds (i.e. the object is a valid path in one of
573       the current filesystems), then TCL_OK is returned.  Otherwise TCL_ERROR
574       is returned, and an error message may be left in the interpreter.
575
576       Tcl_FSGetInternalRep  extracts  the  internal representation of a given
577       path object, in the given filesystem.  If the path object belongs to  a
578       different filesystem, we return NULL. If the internal representation is
579       currently NULL, we attempt to generate it, by calling the  filesystem's
580       Tcl_FSCreateInternalRepProc.
581
582       Returns  NULL  or  a valid internal path representation.  This internal
583       representation is cached, so that repeated calls to this function  will
584       not require additional conversions.
585
586       Tcl_FSGetTranslatedPath  attempts  to  extract the translated path from
587       the given Tcl_Obj.
588
589       If the translation succeeds (i.e. the object is a valid path), then  it
590       is returned.  Otherwise NULL will be returned, and an error message may
591       be left in the interpreter.  A "translated" path is one which  contains
592       no  "~" or "~user" sequences (these have been expanded to their current
593       representation in the filesystem).  The object returned is owned by the
594       caller,  which  must store it or call Tcl_DecrRefCount to ensure memory
595       is freed.  This function is of little practical use, and  Tcl_FSGetNor‐
596       malizedPath  or  Tcl_GetNativePath  are usually better functions to use
597       for most purposes.
598
599       Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
600       but returns a character string or NULL.  The string returned is dynami‐
601       cally allocated and owned by the caller, which must store  it  or  call
602       ckfree  to  ensure  it  is  freed.   Again,  Tcl_FSGetNormalizedPath or
603       Tcl_GetNativePath are usually better functions to  use  for  most  pur‐
604       poses.
605
606       Tcl_FSNewNativePath  performs  something like that reverse of the usual
607       obj->path->nativerep conversions.  If some code  retrieves  a  path  in
608       native  form (from, e.g. readlink or a native dialog), and that path is
609       to be used at the Tcl level, then calling this function is an efficient
610       way of creating the appropriate path object type.
611
612       The resulting object is a pure 'path' object, which will only receive a
613       Utf-8 string representation if that is required by some Tcl code.
614
615       Tcl_FSGetNativePath is for use by the  Win/Unix/MacOS  native  filesys‐
616       tems,  so  that  they  can easily retrieve the native (char* or TCHAR*)
617       representation of a path.   This  function  is  a  convenience  wrapper
618       around  Tcl_FSGetInternalRep,  and assumes the native representation is
619       string-based.  It may be desirable in the future  to  have  non-string-
620       based  native  representations (for example, on MacOS, a representation
621       using a fileSpec of FSRef structure would probably be more  efficient).
622       On  Windows  a  full  Unicode  representation  would allow for paths of
623       unlimited length.  Currently the representation is simply  a  character
624       string containing the complete, absolute path in the native encoding.
625
626       The  native  representation  is  cached  so that repeated calls to this
627       function will not require additional conversions.
628
629       Tcl_FSFileSystemInfo returns a list of two elements.  The first element
630       is  the  name  of  the  filesystem  (e.g. "native" or "vfs" or "zip" or
631       "prowrap", perhaps), and the second is the particular type of the given
632       path  within that filesystem (which is filesystem dependent).  The sec‐
633       ond element may be empty if the filesystem does not provide  a  further
634       categorization of files.
635
636       A  valid  list object is returned, unless the path object is not recog‐
637       nized, when NULL will be returned.
638
639       Tcl_FSGetFileSystemForPath returns the a pointer to the  Tcl_Filesystem
640       which accepts this path as valid.
641
642       If no filesystem will accept the path, NULL is returned.
643
644       Tcl_FSGetPathType  determines whether the given path is relative to the
645       current directory, relative to the current volume, or absolute.
646
647       It   returns   one   of   TCL_PATH_ABSOLUTE,   TCL_PATH_RELATIVE,    or
648       TCL_PATH_VOLUME_RELATIVE
649
650       Tcl_AllocStatBuf  allocates a Tcl_StatBuf on the system heap (which may
651       be deallocated by being passed to ckfree.)  This allows  extensions  to
652       invoke  Tcl_FSStat  and Tcl_FSLStat without being dependent on the size
653       of the buffer.  That in turn depends on the flags used to build Tcl.
654

TCL_FILESYSTEM

656       A filesystem provides a Tcl_Filesystem structure that contains pointers
657       to  functions  that  implement  the various operations on a filesystem;
658       these operations are invoked as needed by the generic layer, which gen‐
659       erally occurs through the functions listed above.
660
661       The Tcl_Filesystem structures are manipulated using the following meth‐
662       ods.
663
664       Tcl_FSRegister takes  a  pointer  to  a  filesystem  structure  and  an
665       optional  piece of data to associated with that filesystem.  On calling
666       this function, Tcl will attach the filesystem  to  the  list  of  known
667       filesystems, and it will become fully functional immediately.  Tcl does
668       not check if the same filesystem is registered multiple times  (and  in
669       general that is not a good thing to do).  TCL_OK will be returned.
670
671       Tcl_FSUnregister  removes  the given filesystem structure from the list
672       of known filesystems, if it is  known,  and  returns  TCL_OK.   If  the
673       filesystem is not currently registered, TCL_ERROR is returned.
674
675       Tcl_FSData  will  return  the  ClientData  associated  with  the  given
676       filesystem, if that filesystem is registered.  Otherwise it will return
677       NULL.
678
679       Tcl_FSMountsChanged  is  used  to inform the Tcl's core that the set of
680       mount  points  for  the  given  (already  registered)  filesystem  have
681       changed,  and  that cached file representations may therefore no longer
682       be correct.
683
684       The Tcl_Filesystem structure contains the following fields:
685              typedef struct Tcl_Filesystem {
686                  CONST char *typeName;
687                  int structureLength;
688                  Tcl_FSVersion version;
689                  Tcl_FSPathInFilesystemProc *pathInFilesystemProc;
690                  Tcl_FSDupInternalRepProc *dupInternalRepProc;
691                  Tcl_FSFreeInternalRepProc *freeInternalRepProc;
692                  Tcl_FSInternalToNormalizedProc *internalToNormalizedProc;
693                  Tcl_FSCreateInternalRepProc *createInternalRepProc;
694                  Tcl_FSNormalizePathProc *normalizePathProc;
695                  Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc;
696                  Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc;
697                  Tcl_FSStatProc *statProc;
698                  Tcl_FSAccessProc *accessProc;
699                  Tcl_FSOpenFileChannelProc *openFileChannelProc;
700                  Tcl_FSMatchInDirectoryProc *matchInDirectoryProc;
701                  Tcl_FSUtimeProc *utimeProc;
702                  Tcl_FSLinkProc *linkProc;
703                  Tcl_FSListVolumesProc *listVolumesProc;
704                  Tcl_FSFileAttrStringsProc *fileAttrStringsProc;
705                  Tcl_FSFileAttrsGetProc *fileAttrsGetProc;
706                  Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
707                  Tcl_FSCreateDirectoryProc *createDirectoryProc;
708                  Tcl_FSRemoveDirectoryProc *removeDirectoryProc;
709                  Tcl_FSDeleteFileProc *deleteFileProc;
710                  Tcl_FSCopyFileProc *copyFileProc;
711                  Tcl_FSRenameFileProc *renameFileProc;
712                  Tcl_FSCopyDirectoryProc *copyDirectoryProc;
713                  Tcl_FSLstatProc *lstatProc;
714                  Tcl_FSLoadFileProc *loadFileProc;
715                  Tcl_FSGetCwdProc *getCwdProc;
716                  Tcl_FSChdirProc *chdirProc;
717              } Tcl_Filesystem;
718
719       Except for the first three fields in this structure which contain  sim‐
720       ple data elements, all entries contain addresses of functions called by
721       the generic filesystem layer to perform the complete range of  filesys‐
722       tem related actions.
723
724       The  many  functions in this structure are broken down into three cate‐
725       gories: infrastructure functions (almost all of which  must  be  imple‐
726       mented), operational functions (which must be implemented if a complete
727       filesystem is provided), and efficiency functions (which need  only  be
728       implemented  if  they can be done so efficiently, or if they have side-
729       effects which are required by the filesystem; Tcl  has  less  efficient
730       emulations  it can fall back on).  It is important to note that, in the
731       current version of Tcl, most of these fallbacks are only used to handle
732       commands  initiated  in  Tcl,  not  in C. What this means is, that if a
733       'file rename' command is issued in Tcl, and the relevant  filesystem(s)
734       do  not  implement  their Tcl_FSRenameFileProc, Tcl's core will instead
735       fallback on a combination of other filesystem functions  (it  will  use
736       Tcl_FSCopyFileProc followed by Tcl_FSDeleteFileProc, and if Tcl_FSCopy‐
737       FileProc is not implemented there is a further fallback).  However,  if
738       a  Tcl_FSRenameFile command is issued at the C level, no such fallbacks
739       occur.  This is true except for the last four entries in the filesystem
740       table  (lstat,  load,  getcwd and chdir) for which fallbacks do in fact
741       occur at the C level.
742
743       As an example, here is the filesystem lookup table used  by  the  "vfs"
744       extension which allows filesystem actions to be implemented in Tcl.
745              static Tcl_Filesystem vfsFilesystem = {
746                  "tclvfs",
747                  sizeof(Tcl_Filesystem),
748                  TCL_FILESYSTEM_VERSION_1,
749                  &VfsPathInFilesystem,
750                  &VfsDupInternalRep,
751                  &VfsFreeInternalRep,
752                  /* No internal to normalized, since we don't create any
753                   * pure 'internal' Tcl_Obj path representations */
754                  NULL,
755                  /* No create native rep function, since we don't use it
756                   * and don't choose to support uses of 'Tcl_FSNewNativePath' */
757                  NULL,
758                  /* Normalize path isn't needed - we assume paths only have
759                   * one representation */
760                  NULL,
761                  &VfsFilesystemPathType,
762                  &VfsFilesystemSeparator,
763                  &VfsStat,
764                  &VfsAccess,
765                  &VfsOpenFileChannel,
766                  &VfsMatchInDirectory,
767                  &VfsUtime,
768                  /* We choose not to support symbolic links inside our vfs's */
769                  NULL,
770                  &VfsListVolumes,
771                  &VfsFileAttrStrings,
772                  &VfsFileAttrsGet,
773                  &VfsFileAttrsSet,
774                  &VfsCreateDirectory,
775                  &VfsRemoveDirectory,
776                  &VfsDeleteFile,
777                  /* No copy file - fallback will occur at Tcl level */
778                  NULL,
779                  /* No rename file - fallback will occur at Tcl level */
780                  NULL,
781                  /* No copy directory - fallback will occur at Tcl level */
782                  NULL,
783                  /* Core will use stat for lstat */
784                  NULL,
785                  /* No load - fallback on core implementation */
786                  NULL,
787                  /* We don't need a getcwd or chdir - fallback on Tcl's versions */
788                  NULL,
789                  NULL
790              };
791
792       Any functions which take path names in Tcl_Obj form take those names in
793       UTF-8 form.  The filesystem infrastructure API is designed  to  support
794       efficient,  cached conversion of these UTF-8 paths to other native rep‐
795       resentations.
796

TYPENAME

798       The typeName field contains a null-terminated  string  that  identifies
799       the type of the filesystem implemented, e.g.  native or zip or vfs.
800

STRUCTURE LENGTH

802       The    structureLength    field    is    generally    implemented    as
803       sizeof(Tcl_Filesystem), and is there to allow easier  binary  backwards
804       compatibility  if  the  size  of  the structure changes in a future Tcl
805       release.
806

VERSION

808       The version field should be set to TCL_FILESYSTEM_VERSION_1.
809

FILESYSTEM INFRASTRUCTURE

811       These fields contain addresses of functions which are used to associate
812       a  particular  filesystem  with a file path, and deal with the internal
813       handling of path representations, for example copying and freeing  such
814       representations.
815

PATHINFILESYSTEMPROC

817       The pathInFilesystemProc field contains the address of a function which
818       is called to determine whether a given  path  object  belongs  to  this
819       filesystem or not.  Tcl will only call the rest of the filesystem func‐
820       tions with a path for which this function has returned TCL_OK.  If  the
821       path  does  not belong, -1 should be returned (the behaviour of Tcl for
822       any other return value is not defined).  If TCL_OK  is  returned,  then
823       the  optional  clientDataPtr  output parameter can be used to return an
824       internal (filesystem specific) representation of the path,  which  will
825       be  cached  inside the path object, and may be retrieved efficiently by
826       the other filesystem functions.  Tcl will simultaneously cache the fact
827       that this path belongs to this filesystem.  Such caches are invalidated
828       when filesystem structures are added or  removed  from  Tcl's  internal
829       list of known filesystems.
830
831              typedef int Tcl_FSPathInFilesystemProc(
832                Tcl_Obj *pathPtr,
833                ClientData *clientDataPtr);
834

DUPINTERNALREPPROC

836       This  function makes a copy of a path's internal representation, and is
837       called when Tcl needs to duplicate a path object.  If  NULL,  Tcl  will
838       simply  not copy the internal representation, which may then need to be
839       regenerated later.
840
841              typedef ClientData Tcl_FSDupInternalRepProc(
842                ClientData clientData);
843

FREEINTERNALREPPROC

845       Free the internal representation.  This must be implemented if internal
846       representations  need freeing (i.e. if some memory is allocated when an
847       internal representation is generated), but may otherwise be NULL.
848
849              typedef void Tcl_FSFreeInternalRepProc(
850                ClientData clientData);
851

INTERNALTONORMALIZEDPROC

853       Function to convert internal representation to a normalized path.  Only
854       required   if   the  filesystem  creates  pure  path  objects  with  no
855       string/path representation.  The return value is  a  Tcl  object  whose
856       string representation is the normalized path.
857
858              typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
859                ClientData clientData);
860

CREATEINTERNALREPPROC

862       Function  to  take a path object, and calculate an internal representa‐
863       tion for it, and store that native representation in the  object.   May
864       be   NULL   if  paths  have  no  internal  representation,  or  if  the
865       Tcl_FSPathInFilesystemProc for this filesystem always immediately  cre‐
866       ates an internal representation for paths it accepts.
867
868              typedef ClientData Tcl_FSCreateInternalRepProc(
869                Tcl_Obj *pathPtr);
870

NORMALIZEPATHPROC

872       Function  to  normalize a path.  Should be implemented for all filesys‐
873       tems which can have multiple string representations for the  same  path
874       object.   In  Tcl,  every 'path' must have a single unique 'normalized'
875       string representation.  Depending on the filesystem, there may be  more
876       than  one  unnormalized string representation which refers to that path
877       (e.g. a relative path, a path with  different  character  case  if  the
878       filesystem  is  case  insensitive, a path contain a reference to a home
879       directory such as '~', a path containing symbolic links, etc).  If  the
880       very  last  component  in the path is a symbolic link, it should not be
881       converted into the object it points to (but its case or  other  aspects
882       should  be made unique).  All other path components should be converted
883       from symbolic links.  This one exception  is  required  to  agree  with
884       Tcl's  semantics with 'file delete', 'file rename', 'file copy' operat‐
885       ing on symbolic links.  This function may be  called  with  'nextCheck‐
886       point'  either  at the beginning of the path (i.e. zero), at the end of
887       the path, or at any intermediate file separator in the path.   It  will
888       never point to any other arbitrary position in the path. In the last of
889       the three valid cases, the implementation can assume that the  path  up
890       to and including the file separator is known and normalized.
891
892              typedef int Tcl_FSNormalizePathProc(
893                Tcl_Interp *interp,
894                Tcl_Obj *pathPtr,
895                int nextCheckpoint);
896

FILESYSTEM OPERATIONS

898       The  fields in this section of the structure contain addresses of func‐
899       tions which are called to carry out the basic filesystem operations.  A
900       filesystem which expects to be used with the complete standard Tcl com‐
901       mand set must implement all of these.  If some of them are  not  imple‐
902       mented,  then  certain  Tcl  commands  may fail when operating on paths
903       within that filesystem.  However, in some instances this may be  desir‐
904       able (for example, a read-only filesystem should not implement the last
905       four functions, and a filesystem which does not support symbolic  links
906       need  not  implement  the readlink function, etc.  The Tcl core expects
907       filesystems to behave in this way).
908

FILESYSTEMPATHTYPEPROC

910       Function to determine the type of a path in this  filesystem.   May  be
911       NULL,  in  which case no type information will be available to users of
912       the filesystem.  The 'type' is used only  for  informational  purposes,
913       and  should  be  returned  as  the string representation of the Tcl_Obj
914       which is returned.  A typical return value might be "networked",  "zip"
915       or  "ftp".   The  Tcl_Obj  result is owned by the filesystem and so Tcl
916       will increment the refCount of that object if it  wishes  to  retain  a
917       reference to it.
918
919              typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc(
920                Tcl_Obj *pathPtr);
921

FILESYSTEMSEPARATORPROC

923       Function  to  return  the  separator  character(s) for this filesystem.
924       Must be implemented, otherwise the  file  separator  command  will  not
925       function  correctly.  The usual return value will be a Tcl_Obj contain‐
926       ing the string "/".
927
928              typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
929                Tcl_Obj *pathPtr);
930

STATPROC

932       Function to process a Tcl_FSStat() call.  Must be implemented  for  any
933       reasonable  filesystem,  since many Tcl level commands depend crucially
934       upon it (e.g. file atime, file isdirectory, file size, glob).
935
936              typedef int Tcl_FSStatProc(
937                Tcl_Obj *pathPtr,
938                Tcl_StatBuf *statPtr);
939
940       The Tcl_FSStatProc fills the stat structure  statPtr  with  information
941       about  the  specified  file.   You do not need any access rights to the
942       file to get this information but you need search rights to all directo‐
943       ries  named  in  the  path  leading  to  the  file.  The stat structure
944       includes info regarding device, inode (always 0 on Windows),  privilege
945       mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
946       id (always 0 on Windows), rdev (same as device on Windows), size,  last
947       access time, last modification time, and creation time.
948
949       If the file represented by pathPtr exists, the Tcl_FSStatProc returns 0
950       and the stat structure is filled with data.  Otherwise, -1 is returned,
951       and no stat info is given.
952

ACCESSPROC

954       Function to process a Tcl_FSAccess() call.  Must be implemented for any
955       reasonable filesystem, since many Tcl level commands  depend  crucially
956       upon it (e.g. file exists, file readable).
957
958              typedef int Tcl_FSAccessProc(
959                Tcl_Obj *pathPtr,
960                int mode);
961
962       The  Tcl_FSAccessProc  checks  whether  the process would be allowed to
963       read, write or test for existence of the file  (or  other  file  system
964       object)  whose  name is pathname.  If pathname is a symbolic link, then
965       permissions of the file  referred  by  this  symbolic  link  should  be
966       tested.
967
968       On  success  (all requested permissions granted), zero is returned.  On
969       error (at least one bit in mode asked for a permission that is  denied,
970       or some other  error occurred), -1 is returned.
971

OPENFILECHANNELPROC

973       Function  to  process  a  Tcl_FSOpenFileChannel() call.  Must be imple‐
974       mented for  any  reasonable  filesystem,  since  any  operations  which
975       require  open  or  accessing  a file's contents will use it (e.g. open,
976       encoding, and many Tk commands).
977
978              typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
979                Tcl_Interp *interp,
980                Tcl_Obj *pathPtr,
981                int mode,
982                int permissions);
983
984       The Tcl_FSOpenFileChannelProc opens a file  specified  by  pathPtr  and
985       returns  a  channel handle that can be used to perform input and output
986       on the file.  This API is modeled after the fopen procedure of the Unix
987       standard I/O library.  The syntax and meaning of all arguments is simi‐
988       lar to those given in the Tcl open command when opening a  file,  where
989       the  mode  argument  is  a  combination  of  the  POSIX flags O_RDONLY,
990       O_WRONLY, etc.  If an error  occurs  while  opening  the  channel,  the
991       Tcl_FSOpenFileChannelProc  returns  NULL and records a POSIX error code
992       that can be retrieved with Tcl_GetErrno.  In  addition,  if  interp  is
993       non-NULL,  the  Tcl_FSOpenFileChannelProc  leaves  an  error message in
994       interp's result after any error.
995
996       The newly created channel is not  registered  in  the  supplied  inter‐
997       preter; to register it, use Tcl_RegisterChannel. If one of the standard
998       channels, stdin, stdout or stderr was previously  closed,  the  act  of
999       creating the new channel also assigns it as a replacement for the stan‐
1000       dard channel.
1001

MATCHINDIRECTORYPROC

1003       Function to process a Tcl_FSMatchInDirectory()  call.   If  not  imple‐
1004       mented,  then  glob and recursive copy functionality will be lacking in
1005       the filesystem (and this may  impact  commands  like  'encoding  names'
1006       which use glob functionality internally).
1007
1008              typedef int Tcl_FSMatchInDirectoryProc(
1009                Tcl_Interp* interp,
1010                Tcl_Obj *result,
1011                Tcl_Obj *pathPtr,
1012                CONST char *pattern,
1013                Tcl_GlobTypeData * types);
1014
1015       The  function should return all files or directories (or other filesys‐
1016       tem objects) which match the given pattern and accord  with  the  types
1017       specification  given.  There are two ways in which this function may be
1018       called.  If pattern is NULL, then pathPtr is a full path  specification
1019       of a single file or directory which should be checked for existence and
1020       correct type.  Otherwise, pathPtr is a directory, the contents of which
1021       the function should search for files or directories which have the cor‐
1022       rect type.  In either case, pathPtr can be assumed to be both  non-NULL
1023       and  non-empty.   It  is  not currently documented whether pathPtr will
1024       have a file separator at its end of not, so code should be flexible  to
1025       both possibilities.
1026
1027       The  return  value is a standard Tcl result indicating whether an error
1028       occurred in the matching process.  Error messages are placed in interp;
1029       on  a TCL_OK result, results should be added to the result object given
1030       (which can be assumed to be a valid unshared Tcl  list).   The  matches
1031       added  to  result should include any path prefix given in pathPtr (this
1032       usually means they will be absolute path specifications).  Note that if
1033       no  matches are found, that simply leads to an empty result; errors are
1034       only signaled for actual file or filesystem problems  which  may  occur
1035       during the matching process.
1036
1037       The  Tcl_GlobTypeData  structure passed in the types parameter contains
1038       the following fields:
1039              typedef struct Tcl_GlobTypeData {
1040                    /* Corresponds to bcdpfls as in 'find -t' */
1041                    int type;
1042                    /* Corresponds to file permissions */
1043                    int perm;
1044                    /* Acceptable mac type */
1045                    Tcl_Obj *macType;
1046                    /* Acceptable mac creator */
1047                    Tcl_Obj *macCreator;
1048              } Tcl_GlobTypeData;
1049
1050       There are two specific cases which it is important to handle correctly,
1051       both  when  types  is  non-NULL.  The two cases are when types->types &
1052       TCL_GLOB_TYPE_DIR or types->types & TCL_GLOB_TYPE_MOUNT are  true  (and
1053       in  particular  when the other flags are false).  In the first of these
1054       cases, the function must list the contained directories.  Tcl uses this
1055       to  implement  recursive  globbing,  so it is critical that filesystems
1056       implement directory matching correctly.  In the second of these  cases,
1057       with  TCL_GLOB_TYPE_MOUNT,  the  filesystem  must list the mount points
1058       which lie within the given pathPtr (and in this case, pathPtr need  not
1059       lie  within the same filesystem - different to all other cases in which
1060       this function is called).  Support for this is critical if  Tcl  is  to
1061       have seamless transitions between from one filesystem to another.
1062

UTIMEPROC

1064       Function  to  process  a Tcl_FSUtime() call.  Required to allow setting
1065       (not reading) of times with 'file mtime', 'file atime'  and  the  open-
1066       r/open-w/fcopy implementation of 'file copy'.
1067
1068              typedef int Tcl_FSUtimeProc(
1069                Tcl_Obj *pathPtr,
1070                struct utimbuf *tval);
1071
1072       The  access  and  modification  times  of the file specified by pathPtr
1073       should be changed to the values given in the tval structure.
1074
1075       The return value is a standard Tcl result indicating whether  an  error
1076       occurred in the process.
1077

LINKPROC

1079       Function to process a Tcl_FSLink() call.  Should be implemented only if
1080       the filesystem supports links, and may otherwise be NULL.
1081
1082              typedef Tcl_Obj* Tcl_FSLinkProc(
1083                Tcl_Obj *linkNamePtr,
1084                Tcl_Obj *toPtr,
1085                int linkAction);
1086
1087       If toPtr is NULL, the function is being asked to read the contents of a
1088       link.   The  result  is  a  Tcl_Obj specifying the contents of the link
1089       given by linkNamePtr, or NULL if the  link  could  not  be  read.   The
1090       result  is owned by the caller, which should call Tcl_DecrRefCount when
1091       the result is no longer needed.  If toPtr is  not  NULL,  the  function
1092       should  attempt  to  create  a link.  The result in this case should be
1093       toPtr if the link was successful and NULL otherwise.  In this case  the
1094       result is not owned by the caller. See the documentation for Tcl_FSLink
1095       for the correct interpretation of the linkAction flags.
1096

LISTVOLUMESPROC

1098       Function to list any  filesystem  volumes  added  by  this  filesystem.
1099       Should  be  implemented only if the filesystem adds volumes at the head
1100       of the filesystem, so that they can be returned by 'file volumes'.
1101
1102              typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
1103
1104       The result should be a list of volumes added  by  this  filesystem,  or
1105       NULL  (or an empty list) if no volumes are provided.  The result object
1106       is considered to be owned by the filesystem (not by  Tcl's  core),  but
1107       should  be  given a refCount for Tcl.  Tcl will use the contents of the
1108       list and then decrement that  refCount.   This  allows  filesystems  to
1109       choose  whether they actually want to retain a 'master list' of volumes
1110       or not (if not, they generate the list on the fly and pass  it  to  Tcl
1111       with  a refCount of 1 and then forget about the list, if yes, then they
1112       simply increment the refCount of their master list and pass it  to  Tcl
1113       which will copy the contents and then decrement the count back to where
1114       it was).
1115
1116       Therefore, Tcl considers return values from this proc to be read-only.
1117

FILEATTRSTRINGSPROC

1119       Function to list  all  attribute  strings  which  are  valid  for  this
1120       filesystem.   If  not  implemented  the filesystem will not support the
1121       file attributes command.  This allows arbitrary additional  information
1122       to  be  attached to files in the filesystem.  If it is not implemented,
1123       there is no need to implement the get and set methods.
1124
1125              typedef CONST char** Tcl_FSFileAttrStringsProc(
1126                Tcl_Obj *pathPtr,
1127                Tcl_Obj** objPtrRef);
1128
1129       The called function may either return  an  array  of  strings,  or  may
1130       instead return NULL and place a Tcl list into the given objPtrRef.  Tcl
1131       will take that list and first increment its refCount before  using  it.
1132       On  completion  of that use, Tcl will decrement its refCount.  Hence if
1133       the list should be disposed of by Tcl when done, it should have a  ref‐
1134       Count  of zero, and if the list should not be disposed of, the filesys‐
1135       tem should ensure it retains a refCount on the object.
1136

FILEATTRSGETPROC

1138       Function  to  process  a  Tcl_FSFileAttrsGet()  call,  used  by   'file
1139       attributes'.
1140
1141              typedef int Tcl_FSFileAttrsGetProc(
1142                Tcl_Interp *interp,
1143                int index,
1144                Tcl_Obj *pathPtr,
1145                Tcl_Obj **objPtrRef);
1146
1147       Returns  a  standard  Tcl  return code.  The attribute value retrieved,
1148       which corresponds to the index'th element in the list returned  by  the
1149       Tcl_FSFileAttrStringsProc,  is a Tcl_Obj placed in objPtrRef (if TCL_OK
1150       was returned) and is likely to have a refCount of zero.  Either way  we
1151       must  either store it somewhere (e.g. the Tcl result), or Incr/Decr its
1152       refCount to ensure it is properly freed.
1153

FILEATTRSSETPROC

1155       Function  to  process  a  Tcl_FSFileAttrsSet()  call,  used  by   'file
1156       attributes'.   If  the  filesystem  is  read-only,  there is no need to
1157       implement this.
1158
1159              typedef int Tcl_FSFileAttrsSetProc(
1160                Tcl_Interp *interp,
1161                int index,
1162                Tcl_Obj *pathPtr,
1163                Tcl_Obj *objPtr);
1164
1165       The attribute value of the index'th element in the list returned by the
1166       Tcl_FSFileAttrStringsProc should be set to the objPtr given.
1167

CREATEDIRECTORYPROC

1169       Function  to  process a Tcl_FSCreateDirectory() call.  Should be imple‐
1170       mented unless the FS is read-only.
1171
1172              typedef int Tcl_FSCreateDirectoryProc(
1173                Tcl_Obj *pathPtr);
1174
1175       The return value is a standard Tcl result indicating whether  an  error
1176       occurred  in  the  process.  If successful, a new directory should have
1177       been added to the filesystem in the location specified by pathPtr.
1178

REMOVEDIRECTORYPROC

1180       Function to process a 'Tcl_FSRemoveDirectory()' call.  Should be imple‐
1181       mented unless the FS is read-only.
1182
1183              typedef int Tcl_FSRemoveDirectoryProc(
1184                Tcl_Obj *pathPtr,
1185                int recursive,
1186                Tcl_Obj **errorPtr);
1187
1188       The  return  value is a standard Tcl result indicating whether an error
1189       occurred in the process.  If successful,  the  directory  specified  by
1190       pathPtr should have been removed from the filesystem.  If the recursive
1191       flag is given, then a non-empty directory  should  be  deleted  without
1192       error.  If an error does occur, the name of the file or directory which
1193       caused the error should be placed in errorPtr.
1194

DELETEFILEPROC

1196       Function to process a Tcl_FSDeleteFile() call.  Should  be  implemented
1197       unless the FS is read-only.
1198
1199              typedef int Tcl_FSDeleteFileProc(
1200                Tcl_Obj *pathPtr);
1201
1202       The  return  value is a standard Tcl result indicating whether an error
1203       occurred in the process.  If successful, the file specified by  pathPtr
1204       should  have  been  removed  from  the  filesystem.   Note that, if the
1205       filesystem supports symbolic links, Tcl will always call this  function
1206       and  not  Tcl_FSRemoveDirectoryProc when needed to delete them (even if
1207       they are symbolic links to directories).
1208

FILESYSTEM EFFICIENCY

LSTATPROC

1211       Function to process a Tcl_FSLstat() call.  If not implemented, Tcl will
1212       attempt  to  use the statProc defined above instead.  Therefore it need
1213       only be implemented if a filesystem can differentiate between stat  and
1214       lstat calls.
1215
1216              typedef int Tcl_FSLstatProc(
1217                Tcl_Obj *pathPtr,
1218                Tcl_StatBuf *statPtr);
1219
1220       The  behavior  of  this  function  is  very  similar  to  that  of  the
1221       Tcl_FSStatProc defined above, except that if it is applied  to  a  sym‐
1222       bolic link, it returns information about the link, not about the target
1223       file.
1224

COPYFILEPROC

1226       Function to process a Tcl_FSCopyFile() call.  If  not  implemented  Tcl
1227       will  fall  back  on  open-r,  open-w and fcopy as a copying mechanism.
1228       Therefore it need only be implemented if  the  filesystem  can  perform
1229       that action more efficiently.
1230
1231              typedef int Tcl_FSCopyFileProc(
1232                Tcl_Obj *srcPathPtr,
1233                Tcl_Obj *destPathPtr);
1234
1235       The  return  value is a standard Tcl result indicating whether an error
1236       occurred in the copying process.  Note that, destPathPtr is the name of
1237       the  file  which  should become the copy of srcPathPtr. It is never the
1238       name of a directory into which srcPathPtr could  be  copied  (i.e.  the
1239       function  is  much  simpler than the Tcl level 'file copy' subcommand).
1240       Note that, if the filesystem supports symbolic links, Tcl  will  always
1241       call  this function and not Tcl_FSCopyDirectoryProc when needed to copy
1242       them (even if they are symbolic links to directories).
1243

RENAMEFILEPROC

1245       Function to process a Tcl_FSRenameFile() call.  If not implemented, Tcl
1246       will  fall back on a copy and delete mechanism.  Therefore it need only
1247       be implemented if the filesystem can perform  that  action  more  effi‐
1248       ciently.
1249
1250              typedef int Tcl_FSRenameFileProc(
1251                Tcl_Obj *srcPathPtr,
1252                Tcl_Obj *destPathPtr);
1253
1254       The  return  value is a standard Tcl result indicating whether an error
1255       occurred in the renaming process.
1256

COPYDIRECTORYPROC

1258       Function to process a Tcl_FSCopyDirectory() call.  If not  implemented,
1259       Tcl  will  fall  back  on  a recursive create-dir, file copy mechanism.
1260       Therefore it need only be implemented if  the  filesystem  can  perform
1261       that action more efficiently.
1262
1263              typedef int Tcl_FSCopyDirectoryProc(
1264                Tcl_Obj *srcPathPtr,
1265                Tcl_Obj *destPathPtr,
1266                Tcl_Obj **errorPtr);
1267
1268       The  return  value is a standard Tcl result indicating whether an error
1269       occurred in the copying process.  If an error does occur, the  name  of
1270       the  file  or  directory  which  caused  the  error should be placed in
1271       errorPtr. Note that, destPathPtr is  the  name  of  the  directory-name
1272       which  should become the mirror-image of srcPathPtr. It is not the name
1273       of a directory into which srcPathPtr should be copied (i.e.  the  func‐
1274       tion is much simpler than the Tcl level 'file copy' subcommand).
1275

LOADFILEPROC

1277       Function  to  process a Tcl_FSLoadFile() call.  If not implemented, Tcl
1278       will fall back on a copy to native-temp followed by a Tcl_FSLoadFile on
1279       that  temporary  copy.   Therefore  it  need only be implemented if the
1280       filesystem can load code directly, or it can be implemented  simply  to
1281       return  TCL_ERROR  to  disable  load  functionality  in this filesystem
1282       entirely.
1283
1284              typedef int Tcl_FSLoadFileProc(
1285                Tcl_Interp * interp,
1286                Tcl_Obj *pathPtr,
1287                Tcl_LoadHandle * handlePtr,
1288                Tcl_FSUnloadFileProc * unloadProcPtr);
1289
1290       Returns a standard Tcl completion code.  If an error occurs,  an  error
1291       message is left in the interp's result.  The function dynamically loads
1292       a binary code file into memory.  On a successful  load,  the  handlePtr
1293       should  be filled with a token for the dynamically loaded file, and the
1294       unloadProcPtr should be filled in with the address of a procedure.  The
1295       procedure  will  be  called  with  the given Tcl_LoadHandle as its only
1296       parameter when Tcl needs to unload the file.
1297

UNLOADFILEPROC

1299       Function to unload a previously successfully loaded file.  If load  was
1300       implemented,  then  this  should  also  be implemented, if there is any
1301       cleanup action required.
1302
1303              typedef void Tcl_FSUnloadFileProc(
1304                Tcl_LoadHandle loadHandle);
1305

GETCWDPROC

1307       Function to process a Tcl_FSGetCwd() call.  Most filesystems  need  not
1308       implement  this.   It  will usually only be called once, if 'getcwd' is
1309       called before 'chdir'.  May be NULL.
1310
1311              typedef Tcl_Obj* Tcl_FSGetCwdProc(
1312                Tcl_Interp *interp);
1313
1314       If the filesystem supports a native notion of a current working  direc‐
1315       tory  (which  might  perhaps  change independent of Tcl), this function
1316       should return that cwd as the result, or NULL if the current  directory
1317       could  not  be determined (e.g. the user does not have appropriate per‐
1318       missions on the cwd directory).  If NULL is returned, an error  message
1319       is left in the interp's result.
1320

CHDIRPROC

1322       Function to process a Tcl_FSChdir() call.  If filesystems do not imple‐
1323       ment this, it will be emulated by a series of directory access  checks.
1324       Otherwise,  virtual filesystems which do implement it need only respond
1325       with a positive return result if the dirName  is  a  valid,  accessible
1326       directory  in  their  filesystem.   They  need not remember the result,
1327       since that will be automatically remembered for use  by  GetCwd.   Real
1328       filesystems  should carry out the correct action (i.e. call the correct
1329       system 'chdir' api).
1330
1331              typedef int Tcl_FSChdirProc(
1332                Tcl_Obj *pathPtr);
1333
1334       The Tcl_FSChdirProc changes the applications current working  directory
1335       to  the value specified in pathPtr. The function returns -1 on error or
1336       0 on success.
1337

KEYWORDS

1339       stat access filesystem vfs
1340
1341
1342
1343Tcl                                   8.4                        Filesystem(3)
Impressum