1Filesystem(3) Tcl Library Procedures Filesystem(3)
2______________________________________________________________________________
6
8 Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged,
9 Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile,
10 Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRe‐
11 moveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile,
12 Tcl_FSEvalFileEx, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSLink,
13 Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet,
14 Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel,
15 Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath,
16 Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoin‐
17 ToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTrans‐
18 latedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath,
19 Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_AllocStatBuf - proce‐
20 dures to interact with any filesystem
21
23 #include <tcl.h>
24 int
26 Tcl_FSRegister(clientData, fsPtr)
27 int
29 Tcl_FSUnregister(fsPtr)
30 ClientData
32 Tcl_FSData(fsPtr)
33 void
35 Tcl_FSMountsChanged(fsPtr)
36 Tcl_Filesystem*
38 Tcl_FSGetFileSystemForPath(pathPtr)
39 Tcl_PathType
41 Tcl_FSGetPathType(pathPtr)
42 int
44 Tcl_FSCopyFile(srcPathPtr, destPathPtr)
45 int
47 Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)
48 int
50 Tcl_FSCreateDirectory(pathPtr)
51 int
53 Tcl_FSDeleteFile(pathPtr)
54 int
56 Tcl_FSRemoveDirectory(pathPtr, int recursive, errorPtr)
57 int
59 Tcl_FSRenameFile(srcPathPtr, destPathPtr)
60 Tcl_Obj*
62 Tcl_FSListVolumes(void)
63 int │
65 Tcl_FSEvalFileEx(interp, pathPtr, encodingName) │
66 int
68 Tcl_FSEvalFile(interp, pathPtr)
69 int
71 Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
72 handlePtr, unloadProcPtr)
73 int
75 Tcl_FSMatchInDirectory(interp, resultPtr, pathPtr, pattern, types)
76 Tcl_Obj*
78 Tcl_FSLink(linkNamePtr, toPtr, linkAction)
79 int
81 Tcl_FSLstat(pathPtr, statPtr)
82 int
84 Tcl_FSUtime(pathPtr, tval)
85 int
87 Tcl_FSFileAttrsGet(interp, int index, pathPtr, objPtrRef)
88 int
90 Tcl_FSFileAttrsSet(interp, int index, pathPtr, Tcl_Obj *objPtr)
91 const char**
93 Tcl_FSFileAttrStrings(pathPtr, objPtrRef)
94 int
96 Tcl_FSStat(pathPtr, statPtr)
97 int
99 Tcl_FSAccess(pathPtr, mode)
100 Tcl_Channel
102 Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)
103 Tcl_Obj*
105 Tcl_FSGetCwd(interp)
106 int
108 Tcl_FSChdir(pathPtr)
109 Tcl_Obj*
111 Tcl_FSPathSeparator(pathPtr)
112 Tcl_Obj*
114 Tcl_FSJoinPath(listObj, elements)
115 Tcl_Obj*
117 Tcl_FSSplitPath(pathPtr, lenPtr)
118 int
120 Tcl_FSEqualPaths(firstPtr, secondPtr)
121 Tcl_Obj*
123 Tcl_FSGetNormalizedPath(interp, pathPtr)
124 Tcl_Obj*
126 Tcl_FSJoinToPath(basePtr, objc, objv)
127 int
129 Tcl_FSConvertToPathType(interp, pathPtr)
130 ClientData
132 Tcl_FSGetInternalRep(pathPtr, fsPtr)
133 Tcl_Obj *
135 Tcl_FSGetTranslatedPath(interp, pathPtr)
136 const char *
138 Tcl_FSGetTranslatedStringPath(interp, pathPtr)
139 Tcl_Obj*
141 Tcl_FSNewNativePath(fsPtr, clientData)
142 const char *
144 Tcl_FSGetNativePath(pathPtr)
145 Tcl_Obj*
147 Tcl_FSFileSystemInfo(pathPtr)
148 Tcl_StatBuf*
150 Tcl_AllocStatBuf()
151
153 Tcl_Filesystem *fsPtr (in) Points to a struc‐
154 ture containing the
155 addresses of proce‐
156 dures that can be
157 called to perform
158 the various filesys‐
159 tem operations.
160 Tcl_Obj *pathPtr (in) The path represented
162 by this object is
163 used for the opera‐
164 tion in question.
165 If the object does
166 not already have an
167 internal path repre‐
168 sentation, it will
169 be converted to have
170 one.
171 Tcl_Obj *srcPathPtr (in) As for pathPtr, but
173 used for the source
174 file for a copy or
175 rename operation.
176 Tcl_Obj *destPathPtr (in) As for pathPtr, but
178 used for the desti‐
179 nation filename for
180 a copy or rename
181 operation.
182 const char *encodingName (in) The encoding of the
184 data stored in the
185 file identified by
186 pathPtr and to be
187 evaluated.
188 const char *pattern (in) Only files or direc‐
190 tories matching this
191 pattern will be
192 returned.
193 Tcl_GlobTypeData *types (in) Only files or direc‐
195 tories matching the
196 type descriptions
197 contained in this
198 structure will be
199 returned. This
200 parameter may be
201 NULL.
202 Tcl_Interp *interp (in) Interpreter to use
204 either for results,
205 evaluation, or
206 reporting error mes‐
207 sages.
208 ClientData clientData (in) The native descrip‐
210 tion of the path
211 object to create.
212 Tcl_Obj *firstPtr (in) The first of two
214 path objects to com‐
215 pare. The object
216 may be converted to
217 path type.
218 Tcl_Obj *secondPtr (in) The second of two
220 path objects to com‐
221 pare. The object
222 may be converted to
223 path type.
224 Tcl_Obj *listObj (in) The list of path
226 elements to operate
227 on with a join oper‐
228 ation.
229 int elements (in) If non-negative, the
231 number of elements
232 in the listObj which
233 should be joined
234 together. If nega‐
235 tive, then all ele‐
236 ments are joined.
237 Tcl_Obj **errorPtr (out) In the case of an
239 error, filled with
240 an object containing
241 the name of the file
242 which caused an
243 error in the various
244 copy/rename opera‐
245 tions.
246 Tcl_Obj **objPtrRef (out) Filled with an
248 object containing
249 the result of the
250 operation.
251 Tcl_Obj *resultPtr (out) Pre-allocated object
253 in which to store
254 (using Tcl_ListOb‐
255 jAppendElement) the
256 list of files or
257 directories which
258 are successfully
259 matched.
260 int mode (in) Mask consisting of
262 one or more of R_OK,
263 W_OK, X_OK and F_OK.
264 R_OK, W_OK and X_OK
265 request checking
266 whether the file
267 exists and has
268 read, write and
269 execute permis‐
270 sions, respectively.
271 F_OK just requests
272 checking for the
273 existence of the
274 file.
275 Tcl_StatBuf *statPtr (out) The structure that
277 contains the result
278 of a stat or lstat
279 operation.
280 const char *sym1 (in) Name of a procedure
282 to look up in the
283 file's symbol table
284 const char *sym2 (in) Name of a procedure
286 to look up in the
287 file's symbol table
288 Tcl_PackageInitProc **proc1Ptr (out) Filled with the init
290 function for this
291 code.
292 Tcl_PackageInitProc **proc2Ptr (out) Filled with the
294 safe-init function
295 for this code.
296 ClientData *clientDataPtr (out) Filled with the
298 clientData value to
299 pass to this code's
300 unload function when
301 it is called.
302 Tcl_LoadHandle *handlePtr (out) Filled with an
304 abstract token rep‐
305 resenting the loaded
306 file.
307 Tcl_FSUnloadFileProc **unloadProcPtr (out) Filled with the
309 function to use to
310 unload this piece of
311 code.
312 utimbuf *tval (in) The access and modi‐
314 fication times in
315 this structure are
316 read and used to set
317 those values for a
318 given file.
319 const char *modeString (in) Specifies how the
321 file is to be
322 accessed. May have
323 any of the values
324 allowed for the mode
325 argument to the Tcl
326 open command.
327 int permissions (in) POSIX-style permis‐
329 sion flags such as
330 0644. If a new file
331 is created, these
332 permissions will be
333 set on the created
334 file.
335 int *lenPtr (out) If non-NULL, filled
337 with the number of
338 elements in the
339 split path.
340 Tcl_Obj *basePtr (in) The base path on to
342 which to join the
343 given elements. May
344 be NULL.
345 int objc (in) The number of ele‐
347 ments in objv.
348 Tcl_Obj *const objv[] (in) The elements to join
350 to the given base
351 path.
352 Tcl_Obj *linkNamePtr (in) The name of the link
354 to be created or
355 read.
356 Tcl_Obj *toPtr (in) What the link called
358 linkNamePtr should
359 be linked to, or
360 NULL if the symbolic
361 link specified by
362 linkNamePtr is to be
363 read.
364 int linkAction (in) OR-ed combination of
366 flags indicating
367 what kind of link
368 should be created
369 (will be ignored if
370 toPtr is NULL).
371 Valid bits to set
372 are TCL_CREATE_SYM‐
373 BOLIC_LINK and
374 TCL_CRE‐
375 ATE_HARD_LINK. When
376 both flags are set
377 and the underlying
378 filesystem can do
379 either, symbolic
380 links are preferred.
381_________________________________________________________________
382
385 There are several reasons for calling the Tcl_FS API functions (e.g.
386 Tcl_FSAccess and Tcl_FSStat) rather than calling system level functions
387 like access and stat directly. First, they will work cross-platform,
388 so an extension which calls them should work unmodified on Unix and
389 Windows. Second, the Windows implementation of some of these functions
390 fixes some bugs in the system level calls. Third, these function calls
391 deal with any “Utf to platform-native” path conversions which may be
392 required (and may cache the results of such conversions for greater
393 efficiency on subsequent calls). Fourth, and perhaps most importantly,
394 all of these functions are “virtual filesystem aware”. Any virtual
395 filesystem (VFS for short) which has been registered (through
396 Tcl_FSRegister) may reroute file access to alternative media or access
397 methods. This means that all of these functions (and therefore the
398 corresponding file, glob, pwd, cd, open, etc. Tcl commands) may be
399 operate on “files” which are not native files in the native filesystem.
400 This also means that any Tcl extension which accesses the filesystem
401 (FS for short) through this API is automatically “virtual filesystem
402 aware”. Of course, if an extension accesses the native filesystem
403 directly (through platform-specific APIs, for example), then Tcl cannot
404 intercept such calls.
405 If appropriate VFSes have been registered, the “files” may, to give two
407 examples, be remote (e.g. situated on a remote ftp server) or archived
408 (e.g. lying inside a .zip archive). Such registered filesystems pro‐
409 vide a lookup table of functions to implement all or some of the func‐
410 tionality listed here. Finally, the Tcl_FSStat and Tcl_FSLstat calls
411 abstract away from what the “struct stat” buffer is actually declared
412 to be, allowing the same code to be used both on systems with and sys‐
413 tems without support for files larger than 2GB in size.
414 The Tcl_FS API is objectified and may cache internal representations
416 and other path-related strings (e.g. the current working directory).
417 One side-effect of this is that one must not pass in objects with a
418 reference count of zero to any of these functions. If such calls were
419 handled, they might result in memory leaks (under some circumstances,
420 the filesystem code may wish to retain a reference to the passed in
421 object, and so one must not assume that after any of these calls
422 return, the object still has a reference count of zero - it may have
423 been incremented) or in a direct segmentation fault (or other memory
424 access error) due to the object being freed part way through the com‐
425 plex object manipulation required to ensure that the path is fully nor‐
426 malized and absolute for filesystem determination. The practical les‐
427 son to learn from this is that
428 Tcl_Obj *path = Tcl_NewStringObj(...);
429 Tcl_FSWhatever(path);
430 Tcl_DecrRefCount(path);
431 is wrong, and may cause memory errors. The path must have its reference
432 count incremented before passing it in, or decrementing it. For this
433 reason, objects with a reference count of zero are considered not to be
434 valid filesystem paths and calling any Tcl_FS API function with such an
435 object will result in no action being taken.
436 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 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 Tcl_FSCreateDirectory attempts to create the directory given by pathPtr
453 by calling the owning filesystem's “create directory” function.
454 Tcl_FSDeleteFile attempts to delete the file given by pathPtr by call‐
456 ing the owning filesystem's “delete file” function.
457 Tcl_FSRemoveDirectory attempts to remove the directory given by pathPtr
459 by calling the owning filesystem's “remove directory” function.
460 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 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 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 Tcl_FSLoadFile dynamically loads a binary code file into memory and
487 returns the addresses of two procedures within that file, if they are
488 defined. The appropriate function for the filesystem to which pathPtr
489 belongs will be called. If that filesystem does not implement this
490 function (most virtual filesystems will not, because of OS limitations
491 in dynamically loading binary code), Tcl will attempt to copy the file
492 to a temporary directory and load that temporary file.
493 Returns a standard Tcl completion code. If an error occurs, an error
495 message is left in the interp's result.
496 Tcl_FSMatchInDirectory is used by the globbing code to search a direc‐
498 tory for all files which match a given pattern. The appropriate func‐
499 tion for the filesystem to which pathPtr belongs will be called.
500 The return value is a standard Tcl result indicating whether an error
502 occurred in globbing. Error messages are placed in interp (unless
503 interp is NULL, which is allowed), but good results are placed in the
504 resultPtr given.
505 Note that the glob code implements recursive patterns internally, so
507 this function will only ever be passed simple patterns, which can be
508 matched using the logic of string match. To handle recursion, Tcl will
509 call this function frequently asking only for directories to be
510 returned. A special case of being called with a NULL pattern indicates
511 that the path needs to be checked only for the correct type.
512 Tcl_FSLink replaces the library version of readlink, and extends it to
514 support the creation of links. The appropriate function for the
515 filesystem to which linkNamePtr belongs will be called.
516 If the toPtr is NULL, a “read link” action is performed. The result is
518 a Tcl_Obj specifying the contents of the symbolic link given by
519 linkNamePtr, or NULL if the link could not be read. The result is
520 owned by the caller, which should call Tcl_DecrRefCount when the result
521 is no longer needed. If the toPtr is not NULL, Tcl should create a
522 link of one of the types passed in in the linkAction flag. This flag
523 is an ORed combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CRE‐
524 ATE_HARD_LINK. Where a choice exists (i.e. more than one flag is
525 passed in), the Tcl convention is to prefer symbolic links. When a
526 link is successfully created, the return value should be toPtr (which
527 is therefore already owned by the caller). If unsuccessful, NULL is
528 returned.
529 Tcl_FSLstat fills the stat structure statPtr with information about the
531 specified file. You do not need any access rights to the file to get
532 this information but you need search rights to all directories named in
533 the path leading to the file. The stat structure includes info regard‐
534 ing device, inode (always 0 on Windows), privilege mode, nlink (always
535 1 on Windows), user id (always 0 on Windows), group id (always 0 on
536 Windows), rdev (same as device on Windows), size, last access time,
537 last modification time, and creation time.
538 If path exists, Tcl_FSLstat returns 0 and the stat structure is filled
540 with data. Otherwise, -1 is returned, and no stat info is given.
541 Tcl_FSUtime replaces the library version of utime.
543 This returns 0 on success and -1 on error (as per the utime documenta‐
545 tion). If successful, the function will update the “atime” and “mtime”
546 values of the file given.
547 Tcl_FSFileAttrsGet implements read access for the hookable file
549 attributes subcommand. The appropriate function for the filesystem to
550 which pathPtr belongs will be called.
551 If the result is TCL_OK, then an object was placed in objPtrRef, which
553 will only be temporarily valid (unless Tcl_IncrRefCount is called).
554 Tcl_FSFileAttrsSet implements write access for the hookable file
556 attributes subcommand. The appropriate function for the filesystem to
557 which pathPtr belongs will be called.
558 Tcl_FSFileAttrStrings implements part of the hookable file attributes
560 subcommand. The appropriate function for the filesystem to which path‐
561 Ptr belongs will be called.
562 The called procedure may either return an array of strings, or may
564 instead return NULL and place a Tcl list into the given objPtrRef. Tcl
565 will take that list and first increment its reference count before
566 using it. On completion of that use, Tcl will decrement its reference
567 count. Hence if the list should be disposed of by Tcl when done, it
568 should have a reference count of zero, and if the list should not be
569 disposed of, the filesystem should ensure it retains a reference count
570 to the object.
571 Tcl_FSAccess checks whether the process would be allowed to read, write
573 or test for existence of the file (or other filesystem object) whose
574 name is pathname. If pathname is a symbolic link on Unix, then per‐
575 missions of the file referred by this symbolic link are tested.
576 On success (all requested permissions granted), zero is returned. On
578 error (at least one bit in mode asked for a permission that is denied,
579 or some other error occurred), -1 is returned.
580 Tcl_FSStat fills the stat structure statPtr with information about the
582 specified file. You do not need any access rights to the file to get
583 this information but you need search rights to all directories named in
584 the path leading to the file. The stat structure includes info regard‐
585 ing device, inode (always 0 on Windows), privilege mode, nlink (always
586 1 on Windows), user id (always 0 on Windows), group id (always 0 on
587 Windows), rdev (same as device on Windows), size, last access time,
588 last modification time, and creation time.
589 If path exists, Tcl_FSStat returns 0 and the stat structure is filled
591 with data. Otherwise, -1 is returned, and no stat info is given.
592 Tcl_FSOpenFileChannel opens a file specified by pathPtr and returns a
594 channel handle that can be used to perform input and output on the
595 file. This API is modeled after the fopen procedure of the Unix stan‐
596 dard I/O library. The syntax and meaning of all arguments is similar
597 to those given in the Tcl open command when opening a file. If an
598 error occurs while opening the channel, Tcl_FSOpenFileChannel returns
599 NULL and records a POSIX error code that can be retrieved with
600 Tcl_GetErrno. In addition, if interp is non-NULL, Tcl_FSOpenFileChan‐
601 nel leaves an error message in interp's result after any error.
602 The newly created channel is not registered in the supplied inter‐
604 preter; to register it, use Tcl_RegisterChannel, described below. If
605 one of the standard channels, stdin, stdout or stderr was previously
606 closed, the act of creating the new channel also assigns it as a
607 replacement for the standard channel.
608 Tcl_FSGetCwd replaces the library version of getcwd.
610 It returns the Tcl library's current working directory. This may be
612 different to the native platform's working directory, which happens
613 when the current working directory is not in the native filesystem.
614 The result is a pointer to a Tcl_Obj specifying the current directory,
616 or NULL if the current directory could not be determined. If NULL is
617 returned, an error message is left in the interp's result.
618 The result already has its reference count incremented for the caller.
620 When it is no longer needed, that reference count should be decre‐
621 mented. This is needed for thread-safety purposes, to allow multiple
622 threads to access this and related functions, while ensuring the
623 results are always valid.
624 Tcl_FSChdir replaces the library version of chdir. The path is normal‐
626 ized and then passed to the filesystem which claims it. If that
627 filesystem does not implement this function, Tcl will fallback to a
628 combination of stat and access to check whether the directory exists
629 and has appropriate permissions.
630 For results, see chdir documentation. If successful, we keep a record
632 of the successful path in cwdPathPtr for subsequent calls to
633 Tcl_FSGetCwd.
634 Tcl_FSPathSeparator returns the separator character to be used for most
636 specific element of the path specified by pathPtr (i.e. the last part
637 of the path).
638 The separator is returned as a Tcl_Obj containing a string of length 1.
640 If the path is invalid, NULL is returned.
641 Tcl_FSJoinPath takes the given Tcl_Obj, which must be a valid list
643 (which is allowed to have a reference count of zero), and returns the
644 path object given by considering the first elements elements as valid
645 path segments (each path segment may be a complete path, a partial path
646 or just a single possible directory or file name). If any path segment
647 is actually an absolute path, then all prior path segments are dis‐
648 carded. If elements is less than 0, we use the entire list.
649 It is possible that the returned object is actually an element of the
651 given list, so the caller should be careful to increment the reference
652 count of the result before freeing the list.
653 The returned object, typically with a reference count of zero (but it
655 could be shared under some conditions), contains the joined path. The
656 caller must add a reference count to the object before using it. In
657 particular, the returned object could be an element of the given list,
658 so freeing the list might free the object prematurely if no reference
659 count has been taken. If the number of elements is zero, then the
660 returned object will be an empty-string Tcl_Obj.
661 Tcl_FSSplitPath takes the given Tcl_Obj, which should be a valid path,
663 and returns a Tcl list object containing each segment of that path as
664 an element. It returns a list object with a reference count of zero.
665 If the passed in lenPtr is non-NULL, the variable it points to will be
666 updated to contain the number of elements in the returned list.
667 Tcl_FSEqualPaths tests whether the two paths given represent the same
669 filesystem object
670 It returns 1 if the paths are equal, and 0 if they are different. If
672 either path is NULL, 0 is always returned.
673 Tcl_FSGetNormalizedPath this important function attempts to extract
675 from the given Tcl_Obj a unique normalized path representation, whose
676 string value can be used as a unique identifier for the file.
677 It returns the normalized path object, owned by Tcl, or NULL if the
679 path was invalid or could otherwise not be successfully converted.
680 Extraction of absolute, normalized paths is very efficient (because the
681 filesystem operates on these representations internally), although the
682 result when the filesystem contains numerous symbolic links may not be
683 the most user-friendly version of a path. The return value is owned by
684 Tcl and has a lifetime equivalent to that of the pathPtr passed in
685 (unless that is a relative path, in which case the normalized path
686 object may be freed any time the cwd changes) - the caller can of
687 course increment the refCount if it wishes to maintain a copy for
688 longer.
689 Tcl_FSJoinToPath takes the given object, which should usually be a
691 valid path or NULL, and joins onto it the array of paths segments
692 given.
693 Returns object, typically with refCount of zero (but it could be shared
695 under some conditions), containing the joined path. The caller must
696 add a refCount to the object before using it. If any of the objects
697 passed into this function (pathPtr or path elements) have a refCount of
698 zero, they will be freed when this function returns.
699 Tcl_FSConvertToPathType tries to convert the given Tcl_Obj to a valid
701 Tcl path type, taking account of the fact that the cwd may have changed
702 even if this object is already supposedly of the correct type. The
703 filename may begin with “~” (to indicate current user's home directory)
704 or “~<user>” (to indicate any user's home directory).
705 If the conversion succeeds (i.e. the object is a valid path in one of
707 the current filesystems), then TCL_OK is returned. Otherwise TCL_ERROR
708 is returned, and an error message may be left in the interpreter.
709 Tcl_FSGetInternalRep extracts the internal representation of a given
711 path object, in the given filesystem. If the path object belongs to a
712 different filesystem, we return NULL. If the internal representation is
713 currently NULL, we attempt to generate it, by calling the filesystem's
714 Tcl_FSCreateInternalRepProc.
715 Returns NULL or a valid internal path representation. This internal
717 representation is cached, so that repeated calls to this function will
718 not require additional conversions.
719 Tcl_FSGetTranslatedPath attempts to extract the translated path from
721 the given Tcl_Obj.
722 If the translation succeeds (i.e. the object is a valid path), then it
724 is returned. Otherwise NULL will be returned, and an error message may
725 be left in the interpreter. A “translated” path is one which contains
726 no “~” or “~user” sequences (these have been expanded to their current
727 representation in the filesystem). The object returned is owned by the
728 caller, which must store it or call Tcl_DecrRefCount to ensure memory
729 is freed. This function is of little practical use, and Tcl_FSGetNor‐
730 malizedPath or Tcl_GetNativePath are usually better functions to use
731 for most purposes.
732 Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
734 but returns a character string or NULL. The string returned is dynami‐
735 cally allocated and owned by the caller, which must store it or call
736 ckfree to ensure it is freed. Again, Tcl_FSGetNormalizedPath or
737 Tcl_GetNativePath are usually better functions to use for most pur‐
738 poses.
739 Tcl_FSNewNativePath performs something like the reverse of the usual
741 obj->path->nativerep conversions. If some code retrieves a path in
742 native form (from, e.g. readlink or a native dialog), and that path is
743 to be used at the Tcl level, then calling this function is an efficient
744 way of creating the appropriate path object type.
745 The resulting object is a pure “path” object, which will only receive a
747 UTF-8 string representation if that is required by some Tcl code.
748 Tcl_FSGetNativePath is for use by the Win/Unix native filesystems, so
750 that they can easily retrieve the native (char* or TCHAR*) representa‐
751 tion of a path. This function is a convenience wrapper around
752 Tcl_FSGetInternalRep, and assumes the native representation is string-
753 based. It may be desirable in the future to have non-string-based
754 native representations (for example, on MacOSX, a representation using
755 a fileSpec of FSRef structure would probably be more efficient). On
756 Windows a full Unicode representation would allow for paths of unlim‐
757 ited length. Currently the representation is simply a character string
758 which may contain either the relative path or a complete, absolute nor‐
759 malized path in the native encoding (complex conditions dictate which
760 of these will be provided, so neither can be relied upon, unless the
761 path is known to be absolute). If you need a native path which must be
762 absolute, then you should ask for the native version of a normalized
763 path. If for some reason a non-absolute, non-normalized version of the
764 path is needed, that must be constructed separately (e.g. using
765 Tcl_FSGetTranslatedPath).
766 The native representation is cached so that repeated calls to this
768 function will not require additional conversions. The return value is
769 owned by Tcl and has a lifetime equivalent to that of the pathPtr
770 passed in (unless that is a relative path, in which case the native
771 representation may be freed any time the cwd changes).
772 Tcl_FSFileSystemInfo returns a list of two elements. The first element
774 is the name of the filesystem (e.g. “native”, “vfs”, “zip”, or
775 “prowrap”, perhaps), and the second is the particular type of the given
776 path within that filesystem (which is filesystem dependent). The sec‐
777 ond element may be empty if the filesystem does not provide a further
778 categorization of files.
779 A valid list object is returned, unless the path object is not recog‐
781 nized, when NULL will be returned.
782 Tcl_FSGetFileSystemForPath returns the a pointer to the Tcl_Filesystem
784 which accepts this path as valid.
785 If no filesystem will accept the path, NULL is returned.
787 Tcl_FSGetPathType determines whether the given path is relative to the
789 current directory, relative to the current volume, or absolute.
790 It returns one of TCL_PATH_ABSOLUTE, TCL_PATH_RELATIVE, or
792 TCL_PATH_VOLUME_RELATIVE
793 Tcl_AllocStatBuf allocates a Tcl_StatBuf on the system heap (which may
795 be deallocated by being passed to ckfree.) This allows extensions to
796 invoke Tcl_FSStat and Tcl_FSLStat without being dependent on the size
797 of the buffer. That in turn depends on the flags used to build Tcl.
798
800 A filesystem provides a Tcl_Filesystem structure that contains pointers
801 to functions that implement the various operations on a filesystem;
802 these operations are invoked as needed by the generic layer, which gen‐
803 erally occurs through the functions listed above.
804 The Tcl_Filesystem structures are manipulated using the following meth‐
806 ods.
807 Tcl_FSRegister takes a pointer to a filesystem structure and an
809 optional piece of data to associated with that filesystem. On calling
810 this function, Tcl will attach the filesystem to the list of known
811 filesystems, and it will become fully functional immediately. Tcl does
812 not check if the same filesystem is registered multiple times (and in
813 general that is not a good thing to do). TCL_OK will be returned.
814 Tcl_FSUnregister removes the given filesystem structure from the list
816 of known filesystems, if it is known, and returns TCL_OK. If the
817 filesystem is not currently registered, TCL_ERROR is returned.
818 Tcl_FSData will return the ClientData associated with the given
820 filesystem, if that filesystem is registered. Otherwise it will return
821 NULL.
822 Tcl_FSMountsChanged is used to inform the Tcl's core that the set of
824 mount points for the given (already registered) filesystem have
825 changed, and that cached file representations may therefore no longer
826 be correct.
827 THE TCL_FILESYSTEM STRUCTURE
829 The Tcl_Filesystem structure contains the following fields:
830 typedef struct Tcl_Filesystem {
831 const char *typeName;
832 int structureLength;
833 Tcl_FSVersion version;
834 Tcl_FSPathInFilesystemProc *pathInFilesystemProc;
835 Tcl_FSDupInternalRepProc *dupInternalRepProc;
836 Tcl_FSFreeInternalRepProc *freeInternalRepProc;
837 Tcl_FSInternalToNormalizedProc *internalToNormalizedProc;
838 Tcl_FSCreateInternalRepProc *createInternalRepProc;
839 Tcl_FSNormalizePathProc *normalizePathProc;
840 Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc;
841 Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc;
842 Tcl_FSStatProc *statProc;
843 Tcl_FSAccessProc *accessProc;
844 Tcl_FSOpenFileChannelProc *openFileChannelProc;
845 Tcl_FSMatchInDirectoryProc *matchInDirectoryProc;
846 Tcl_FSUtimeProc *utimeProc;
847 Tcl_FSLinkProc *linkProc;
848 Tcl_FSListVolumesProc *listVolumesProc;
849 Tcl_FSFileAttrStringsProc *fileAttrStringsProc;
850 Tcl_FSFileAttrsGetProc *fileAttrsGetProc;
851 Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
852 Tcl_FSCreateDirectoryProc *createDirectoryProc;
853 Tcl_FSRemoveDirectoryProc *removeDirectoryProc;
854 Tcl_FSDeleteFileProc *deleteFileProc;
855 Tcl_FSCopyFileProc *copyFileProc;
856 Tcl_FSRenameFileProc *renameFileProc;
857 Tcl_FSCopyDirectoryProc *copyDirectoryProc;
858 Tcl_FSLstatProc *lstatProc;
859 Tcl_FSLoadFileProc *loadFileProc;
860 Tcl_FSGetCwdProc *getCwdProc;
861 Tcl_FSChdirProc *chdirProc;
862 } Tcl_Filesystem;
863 Except for the first three fields in this structure which contain sim‐
865 ple data elements, all entries contain addresses of functions called by
866 the generic filesystem layer to perform the complete range of filesys‐
867 tem related actions.
868 The many functions in this structure are broken down into three cate‐
870 gories: infrastructure functions (almost all of which must be imple‐
871 mented), operational functions (which must be implemented if a complete
872 filesystem is provided), and efficiency functions (which need only be
873 implemented if they can be done so efficiently, or if they have side-
874 effects which are required by the filesystem; Tcl has less efficient
875 emulations it can fall back on). It is important to note that, in the
876 current version of Tcl, most of these fallbacks are only used to handle
877 commands initiated in Tcl, not in C. What this means is, that if a file
878 rename command is issued in Tcl, and the relevant filesystem(s) do not
879 implement their Tcl_FSRenameFileProc, Tcl's core will instead fallback
880 on a combination of other filesystem functions (it will use Tcl_FSCopy‐
881 FileProc followed by Tcl_FSDeleteFileProc, and if Tcl_FSCopyFileProc is
882 not implemented there is a further fallback). However, if a Tcl_FSRe‐
883 nameFileProc command is issued at the C level, no such fallbacks occur.
884 This is true except for the last four entries in the filesystem table
885 (lstat, load, getcwd and chdir) for which fallbacks do in fact occur at
886 the C level.
887 Any functions which take path names in Tcl_Obj form take those names in
889 UTF-8 form. The filesystem infrastructure API is designed to support
890 efficient, cached conversion of these UTF-8 paths to other native rep‐
891 resentations.
892 EXAMPLE FILESYSTEM DEFINITION
894 Here is the filesystem lookup table used by the “vfs” extension which
895 allows filesystem actions to be implemented in Tcl.
896 static Tcl_Filesystem vfsFilesystem = {
897 "tclvfs",
898 sizeof(Tcl_Filesystem),
899 TCL_FILESYSTEM_VERSION_1,
900 &VfsPathInFilesystem,
901 &VfsDupInternalRep,
902 &VfsFreeInternalRep,
903 /* No internal to normalized, since we don't create
904 * any pure 'internal' Tcl_Obj path representations */
905 NULL,
906 /* No create native rep function, since we don't use
907 * it and don't choose to support uses of
908 * Tcl_FSNewNativePath */
909 NULL,
910 /* Normalize path isn't needed - we assume paths only
911 * have one representation */
912 NULL,
913 &VfsFilesystemPathType,
914 &VfsFilesystemSeparator,
915 &VfsStat,
916 &VfsAccess,
917 &VfsOpenFileChannel,
918 &VfsMatchInDirectory,
919 &VfsUtime,
920 /* We choose not to support symbolic links inside our
921 * VFS's */
922 NULL,
923 &VfsListVolumes,
924 &VfsFileAttrStrings,
925 &VfsFileAttrsGet,
926 &VfsFileAttrsSet,
927 &VfsCreateDirectory,
928 &VfsRemoveDirectory,
929 &VfsDeleteFile,
930 /* No copy file; use the core fallback mechanism */
931 NULL,
932 /* No rename file; use the core fallback mechanism */
933 NULL,
934 /* No copy directory; use the core fallback mechanism */
935 NULL,
936 /* Core will use stat for lstat */
937 NULL,
938 /* No load; use the core fallback mechanism */
939 NULL,
940 /* We don't need a getcwd or chdir; the core's own
941 * internal value is suitable */
942 NULL,
943 NULL
944 };
945
947 These fields contain basic information about the filesystem structure
948 and addresses of functions which are used to associate a particular
949 filesystem with a file path, and deal with the internal handling of
950 path representations, for example copying and freeing such representa‐
951 tions.
952 TYPENAME
954 The typeName field contains a null-terminated string that identifies
955 the type of the filesystem implemented, e.g. “native”, “zip” or “vfs”.
956 STRUCTURE LENGTH
958 The structureLength field is generally implemented as
959 sizeof(Tcl_Filesystem), and is there to allow easier binary backwards
960 compatibility if the size of the structure changes in a future Tcl
961 release.
962 VERSION
964 The version field should be set to TCL_FILESYSTEM_VERSION_1.
965 PATHINFILESYSTEMPROC
967 The pathInFilesystemProc field contains the address of a function which
968 is called to determine whether a given path object belongs to this
969 filesystem or not. Tcl will only call the rest of the filesystem func‐
970 tions with a path for which this function has returned TCL_OK. If the
971 path does not belong, -1 should be returned (the behaviour of Tcl for
972 any other return value is not defined). If TCL_OK is returned, then
973 the optional clientDataPtr output parameter can be used to return an
974 internal (filesystem specific) representation of the path, which will
975 be cached inside the path object, and may be retrieved efficiently by
976 the other filesystem functions. Tcl will simultaneously cache the fact
977 that this path belongs to this filesystem. Such caches are invalidated
978 when filesystem structures are added or removed from Tcl's internal
979 list of known filesystems.
980 typedef int Tcl_FSPathInFilesystemProc(
982 Tcl_Obj *pathPtr,
983 ClientData *clientDataPtr);
984 DUPINTERNALREPPROC
986 This function makes a copy of a path's internal representation, and is
987 called when Tcl needs to duplicate a path object. If NULL, Tcl will
988 simply not copy the internal representation, which may then need to be
989 regenerated later.
990 typedef ClientData Tcl_FSDupInternalRepProc(
992 ClientData clientData);
993 FREEINTERNALREPPROC
995 Free the internal representation. This must be implemented if internal
996 representations need freeing (i.e. if some memory is allocated when an
997 internal representation is generated), but may otherwise be NULL.
998 typedef void Tcl_FSFreeInternalRepProc(
1000 ClientData clientData);
1001 INTERNALTONORMALIZEDPROC
1003 Function to convert internal representation to a normalized path. Only
1004 required if the filesystem creates pure path objects with no
1005 string/path representation. The return value is a Tcl object whose
1006 string representation is the normalized path.
1007 typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
1009 ClientData clientData);
1010 CREATEINTERNALREPPROC
1012 Function to take a path object, and calculate an internal representa‐
1013 tion for it, and store that native representation in the object. May
1014 be NULL if paths have no internal representation, or if the
1015 Tcl_FSPathInFilesystemProc for this filesystem always immediately cre‐
1016 ates an internal representation for paths it accepts.
1017 typedef ClientData Tcl_FSCreateInternalRepProc(
1019 Tcl_Obj *pathPtr);
1020 NORMALIZEPATHPROC
1022 Function to normalize a path. Should be implemented for all filesys‐
1023 tems which can have multiple string representations for the same path
1024 object. In Tcl, every “path” must have a single unique “normalized”
1025 string representation. Depending on the filesystem, there may be more
1026 than one unnormalized string representation which refers to that path
1027 (e.g. a relative path, a path with different character case if the
1028 filesystem is case insensitive, a path contain a reference to a home
1029 directory such as “~”, a path containing symbolic links, etc). If the
1030 very last component in the path is a symbolic link, it should not be
1031 converted into the object it points to (but its case or other aspects
1032 should be made unique). All other path components should be converted
1033 from symbolic links. This one exception is required to agree with
1034 Tcl's semantics with file delete, file rename, file copy operating on
1035 symbolic links. This function may be called with nextCheckpoint either
1036 at the beginning of the path (i.e. zero), at the end of the path, or at
1037 any intermediate file separator in the path. It will never point to
1038 any other arbitrary position in the path. In the last of the three
1039 valid cases, the implementation can assume that the path up to and
1040 including the file separator is known and normalized.
1041 typedef int Tcl_FSNormalizePathProc(
1043 Tcl_Interp *interp,
1044 Tcl_Obj *pathPtr,
1045 int nextCheckpoint);
1046
1048 The fields in this section of the structure contain addresses of func‐
1049 tions which are called to carry out the basic filesystem operations. A
1050 filesystem which expects to be used with the complete standard Tcl com‐
1051 mand set must implement all of these. If some of them are not imple‐
1052 mented, then certain Tcl commands may fail when operating on paths
1053 within that filesystem. However, in some instances this may be desir‐
1054 able (for example, a read-only filesystem should not implement the last
1055 four functions, and a filesystem which does not support symbolic links
1056 need not implement the readlink function, etc. The Tcl core expects
1057 filesystems to behave in this way).
1058 FILESYSTEMPATHTYPEPROC
1060 Function to determine the type of a path in this filesystem. May be
1061 NULL, in which case no type information will be available to users of
1062 the filesystem. The “type” is used only for informational purposes,
1063 and should be returned as the string representation of the Tcl_Obj
1064 which is returned. A typical return value might be “networked”, “zip”
1065 or “ftp”. The Tcl_Obj result is owned by the filesystem and so Tcl
1066 will increment the refCount of that object if it wishes to retain a
1067 reference to it.
1068 typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc(
1070 Tcl_Obj *pathPtr);
1071 FILESYSTEMSEPARATORPROC
1073 Function to return the separator character(s) for this filesystem.
1074 This need only be implemented if the filesystem wishes to use a differ‐
1075 ent separator than the standard string “/”. Amongst other uses, it is
1076 returned by the file separator command. The return value should be an
1077 object with refCount of zero.
1078 typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
1080 Tcl_Obj *pathPtr);
1081 STATPROC
1083 Function to process a Tcl_FSStat call. Must be implemented for any
1084 reasonable filesystem, since many Tcl level commands depend crucially
1085 upon it (e.g. file atime, file isdirectory, file size, glob).
1086 typedef int Tcl_FSStatProc(
1088 Tcl_Obj *pathPtr,
1089 Tcl_StatBuf *statPtr);
1090 The Tcl_FSStatProc fills the stat structure statPtr with information
1092 about the specified file. You do not need any access rights to the
1093 file to get this information but you need search rights to all directo‐
1094 ries named in the path leading to the file. The stat structure
1095 includes info regarding device, inode (always 0 on Windows), privilege
1096 mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
1097 id (always 0 on Windows), rdev (same as device on Windows), size, last
1098 access time, last modification time, and creation time.
1099 If the file represented by pathPtr exists, the Tcl_FSStatProc returns 0
1101 and the stat structure is filled with data. Otherwise, -1 is returned,
1102 and no stat info is given.
1103 ACCESSPROC
1105 Function to process a Tcl_FSAccess call. Must be implemented for any
1106 reasonable filesystem, since many Tcl level commands depend crucially
1107 upon it (e.g. file exists, file readable).
1108 typedef int Tcl_FSAccessProc(
1110 Tcl_Obj *pathPtr,
1111 int mode);
1112 The Tcl_FSAccessProc checks whether the process would be allowed to
1114 read, write or test for existence of the file (or other filesystem
1115 object) whose name is in pathPtr. If the pathname refers to a symbolic
1116 link, then the permissions of the file referred by this symbolic link
1117 should be tested.
1118 On success (all requested permissions granted), zero is returned. On
1120 error (at least one bit in mode asked for a permission that is denied,
1121 or some other error occurred), -1 is returned.
1122 OPENFILECHANNELPROC
1124 Function to process a Tcl_FSOpenFileChannel call. Must be implemented
1125 for any reasonable filesystem, since any operations which require open
1126 or accessing a file's contents will use it (e.g. open, encoding, and
1127 many Tk commands).
1128 typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
1130 Tcl_Interp *interp,
1131 Tcl_Obj *pathPtr,
1132 int mode,
1133 int permissions);
1134 The Tcl_FSOpenFileChannelProc opens a file specified by pathPtr and
1136 returns a channel handle that can be used to perform input and output
1137 on the file. This API is modeled after the fopen procedure of the Unix
1138 standard I/O library. The syntax and meaning of all arguments is simi‐
1139 lar to those given in the Tcl open command when opening a file, where
1140 the mode argument is a combination of the POSIX flags O_RDONLY,
1141 O_WRONLY, etc. If an error occurs while opening the channel, the
1142 Tcl_FSOpenFileChannelProc returns NULL and records a POSIX error code
1143 that can be retrieved with Tcl_GetErrno. In addition, if interp is
1144 non-NULL, the Tcl_FSOpenFileChannelProc leaves an error message in
1145 interp's result after any error.
1146 The newly created channel is not registered in the supplied inter‐
1148 preter; to register it, use Tcl_RegisterChannel. If one of the standard
1149 channels, stdin, stdout or stderr was previously closed, the act of
1150 creating the new channel also assigns it as a replacement for the stan‐
1151 dard channel.
1152 MATCHINDIRECTORYPROC
1154 Function to process a Tcl_FSMatchInDirectory call. If not implemented,
1155 then glob and recursive copy functionality will be lacking in the
1156 filesystem (and this may impact commands like encoding names which use
1157 glob functionality internally).
1158 typedef int Tcl_FSMatchInDirectoryProc(
1160 Tcl_Interp* interp,
1161 Tcl_Obj *resultPtr,
1162 Tcl_Obj *pathPtr,
1163 const char *pattern,
1164 Tcl_GlobTypeData *types);
1165 The function should return all files or directories (or other filesys‐
1167 tem objects) which match the given pattern and accord with the types
1168 specification given. There are two ways in which this function may be
1169 called. If pattern is NULL, then pathPtr is a full path specification
1170 of a single file or directory which should be checked for existence and
1171 correct type. Otherwise, pathPtr is a directory, the contents of which
1172 the function should search for files or directories which have the cor‐
1173 rect type. In either case, pathPtr can be assumed to be both non-NULL
1174 and non-empty. It is not currently documented whether pathPtr will
1175 have a file separator at its end of not, so code should be flexible to
1176 both possibilities.
1177 The return value is a standard Tcl result indicating whether an error
1179 occurred in the matching process. Error messages are placed in interp,
1180 unless interp in NULL in which case no error message need be generated;
1181 on a TCL_OK result, results should be added to the resultPtr object
1182 given (which can be assumed to be a valid unshared Tcl list). The
1183 matches added to resultPtr should include any path prefix given in
1184 pathPtr (this usually means they will be absolute path specifications).
1185 Note that if no matches are found, that simply leads to an empty
1186 result; errors are only signaled for actual file or filesystem problems
1187 which may occur during the matching process.
1188 The Tcl_GlobTypeData structure passed in the types parameter contains
1190 the following fields:
1191 typedef struct Tcl_GlobTypeData {
1192 /* Corresponds to bcdpfls as in 'find -t' */
1193 int type;
1194 /* Corresponds to file permissions */
1195 int perm;
1196 /* Acceptable mac type */
1197 Tcl_Obj *macType;
1198 /* Acceptable mac creator */
1199 Tcl_Obj *macCreator;
1200 } Tcl_GlobTypeData;
1201 There are two specific cases which it is important to handle correctly,
1203 both when types is non-NULL. The two cases are when types->types &
1204 TCL_GLOB_TYPE_DIR or types->types & TCL_GLOB_TYPE_MOUNT are true (and
1205 in particular when the other flags are false). In the first of these
1206 cases, the function must list the contained directories. Tcl uses this
1207 to implement recursive globbing, so it is critical that filesystems
1208 implement directory matching correctly. In the second of these cases,
1209 with TCL_GLOB_TYPE_MOUNT, the filesystem must list the mount points
1210 which lie within the given pathPtr (and in this case, pathPtr need not
1211 lie within the same filesystem - different to all other cases in which
1212 this function is called). Support for this is critical if Tcl is to
1213 have seamless transitions between from one filesystem to another.
1214 UTIMEPROC
1216 Function to process a Tcl_FSUtime call. Required to allow setting (not
1217 reading) of times with file mtime, file atime and the open-r/open-
1218 w/fcopy implementation of file copy.
1219 typedef int Tcl_FSUtimeProc(
1221 Tcl_Obj *pathPtr,
1222 struct utimbuf *tval);
1223 The access and modification times of the file specified by pathPtr
1225 should be changed to the values given in the tval structure.
1226 The return value should be 0 on success and -1 on an error, as with the
1228 system utime.
1229 LINKPROC
1231 Function to process a Tcl_FSLink call. Should be implemented only if
1232 the filesystem supports links, and may otherwise be NULL.
1233 typedef Tcl_Obj* Tcl_FSLinkProc(
1235 Tcl_Obj *linkNamePtr,
1236 Tcl_Obj *toPtr,
1237 int linkAction);
1238 If toPtr is NULL, the function is being asked to read the contents of a
1240 link. The result is a Tcl_Obj specifying the contents of the link
1241 given by linkNamePtr, or NULL if the link could not be read. The
1242 result is owned by the caller (and should therefore have its ref count
1243 incremented before being returned). Any callers should call Tcl_Decr‐
1244 RefCount on this result when it is no longer needed. If toPtr is not
1245 NULL, the function should attempt to create a link. The result in this
1246 case should be toPtr if the link was successful and NULL otherwise. In
1247 this case the result is not owned by the caller (i.e. no ref count
1248 manipulation on either end is needed). See the documentation for
1249 Tcl_FSLink for the correct interpretation of the linkAction flags.
1250 LISTVOLUMESPROC
1252 Function to list any filesystem volumes added by this filesystem.
1253 Should be implemented only if the filesystem adds volumes at the head
1254 of the filesystem, so that they can be returned by file volumes.
1255 typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
1257 The result should be a list of volumes added by this filesystem, or
1259 NULL (or an empty list) if no volumes are provided. The result object
1260 is considered to be owned by the filesystem (not by Tcl's core), but
1261 should be given a refCount for Tcl. Tcl will use the contents of the
1262 list and then decrement that refCount. This allows filesystems to
1263 choose whether they actually want to retain a “master list” of volumes
1264 or not (if not, they generate the list on the fly and pass it to Tcl
1265 with a refCount of 1 and then forget about the list, if yes, then they
1266 simply increment the refCount of their master list and pass it to Tcl
1267 which will copy the contents and then decrement the count back to where
1268 it was).
1269 Therefore, Tcl considers return values from this proc to be read-only.
1271 FILEATTRSTRINGSPROC
1273 Function to list all attribute strings which are valid for this
1274 filesystem. If not implemented the filesystem will not support the
1275 file attributes command. This allows arbitrary additional information
1276 to be attached to files in the filesystem. If it is not implemented,
1277 there is no need to implement the get and set methods.
1278 typedef const char** Tcl_FSFileAttrStringsProc(
1280 Tcl_Obj *pathPtr,
1281 Tcl_Obj** objPtrRef);
1282 The called function may either return an array of strings, or may
1284 instead return NULL and place a Tcl list into the given objPtrRef. Tcl
1285 will take that list and first increment its reference count before
1286 using it. On completion of that use, Tcl will decrement its reference
1287 count. Hence if the list should be disposed of by Tcl when done, it
1288 should have a reference count of zero, and if the list should not be
1289 disposed of, the filesystem should ensure it returns an object with a
1290 reference count of at least one.
1291 FILEATTRSGETPROC
1293 Function to process a Tcl_FSFileAttrsGet call, used by file attributes.
1294 typedef int Tcl_FSFileAttrsGetProc(
1296 Tcl_Interp *interp,
1297 int index,
1298 Tcl_Obj *pathPtr,
1299 Tcl_Obj **objPtrRef);
1300 Returns a standard Tcl return code. The attribute value retrieved,
1302 which corresponds to the index'th element in the list returned by the
1303 Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if TCL_OK
1304 was returned) and is likely to have a reference count of zero. Either
1305 way we must either store it somewhere (e.g. the Tcl result), or
1306 Incr/Decr its reference count to ensure it is properly freed.
1307 FILEATTRSSETPROC
1309 Function to process a Tcl_FSFileAttrsSet call, used by file attributes.
1310 If the filesystem is read-only, there is no need to implement this.
1311 typedef int Tcl_FSFileAttrsSetProc(
1313 Tcl_Interp *interp,
1314 int index,
1315 Tcl_Obj *pathPtr,
1316 Tcl_Obj *objPtr);
1317 The attribute value of the index'th element in the list returned by the
1319 Tcl_FSFileAttrStringsProc should be set to the objPtr given.
1320 CREATEDIRECTORYPROC
1322 Function to process a Tcl_FSCreateDirectory call. Should be imple‐
1323 mented unless the FS is read-only.
1324 typedef int Tcl_FSCreateDirectoryProc(
1326 Tcl_Obj *pathPtr);
1327 The return value is a standard Tcl result indicating whether an error
1329 occurred in the process. If successful, a new directory should have
1330 been added to the filesystem in the location specified by pathPtr.
1331 REMOVEDIRECTORYPROC
1333 Function to process a Tcl_FSRemoveDirectory call. Should be imple‐
1334 mented unless the FS is read-only.
1335 typedef int Tcl_FSRemoveDirectoryProc(
1337 Tcl_Obj *pathPtr,
1338 int recursive,
1339 Tcl_Obj **errorPtr);
1340 The return value is a standard Tcl result indicating whether an error
1342 occurred in the process. If successful, the directory specified by
1343 pathPtr should have been removed from the filesystem. If the recursive
1344 flag is given, then a non-empty directory should be deleted without
1345 error. If this flag is not given, then and the directory is non-empty
1346 a POSIX “EEXIST” error should be signaled. If an error does occur, the
1347 name of the file or directory which caused the error should be placed
1348 in errorPtr.
1349 DELETEFILEPROC
1351 Function to process a Tcl_FSDeleteFile call. Should be implemented
1352 unless the FS is read-only.
1353 typedef int Tcl_FSDeleteFileProc(
1355 Tcl_Obj *pathPtr);
1356 The return value is a standard Tcl result indicating whether an error
1358 occurred in the process. If successful, the file specified by pathPtr
1359 should have been removed from the filesystem. Note that, if the
1360 filesystem supports symbolic links, Tcl will always call this function
1361 and not Tcl_FSRemoveDirectoryProc when needed to delete them (even if
1362 they are symbolic links to directories).
1363
1365 These functions need not be implemented for a particular filesystem
1366 because the core has a fallback implementation available. See each
1367 individual description for the consequences of leaving the field NULL.
1368 LSTATPROC
1370 Function to process a Tcl_FSLstat call. If not implemented, Tcl will
1371 attempt to use the statProc defined above instead. Therefore it need
1372 only be implemented if a filesystem can differentiate between stat and
1373 lstat calls.
1374 typedef int Tcl_FSLstatProc(
1376 Tcl_Obj *pathPtr,
1377 Tcl_StatBuf *statPtr);
1378 The behavior of this function is very similar to that of the
1380 Tcl_FSStatProc defined above, except that if it is applied to a sym‐
1381 bolic link, it returns information about the link, not about the target
1382 file.
1383 COPYFILEPROC
1385 Function to process a Tcl_FSCopyFile call. If not implemented Tcl will
1386 fall back on open-r, open-w and fcopy as a copying mechanism. There‐
1387 fore it need only be implemented if the filesystem can perform that
1388 action more efficiently.
1389 typedef int Tcl_FSCopyFileProc(
1391 Tcl_Obj *srcPathPtr,
1392 Tcl_Obj *destPathPtr);
1393 The return value is a standard Tcl result indicating whether an error
1395 occurred in the copying process. Note that, destPathPtr is the name of
1396 the file which should become the copy of srcPathPtr. It is never the
1397 name of a directory into which srcPathPtr could be copied (i.e. the
1398 function is much simpler than the Tcl level file copy subcommand).
1399 Note that, if the filesystem supports symbolic links, Tcl will always
1400 call this function and not copyDirectoryProc when needed to copy them
1401 (even if they are symbolic links to directories). Finally, if the
1402 filesystem determines it cannot support the file copy action, calling
1403 Tcl_SetErrno(EXDEV) and returning a non-TCL_OK result will tell Tcl to
1404 use its standard fallback mechanisms.
1405 RENAMEFILEPROC
1407 Function to process a Tcl_FSRenameFile call. If not implemented, Tcl
1408 will fall back on a copy and delete mechanism. Therefore it need only
1409 be implemented if the filesystem can perform that action more effi‐
1410 ciently.
1411 typedef int Tcl_FSRenameFileProc(
1413 Tcl_Obj *srcPathPtr,
1414 Tcl_Obj *destPathPtr);
1415 The return value is a standard Tcl result indicating whether an error
1417 occurred in the renaming process. If the filesystem determines it can‐
1418 not support the file rename action, calling Tcl_SetErrno(EXDEV) and
1419 returning a non-TCL_OK result will tell Tcl to use its standard fall‐
1420 back mechanisms.
1421 COPYDIRECTORYPROC
1423 Function to process a Tcl_FSCopyDirectory call. If not implemented,
1424 Tcl will fall back on a recursive file mkdir, file copy mechanism.
1425 Therefore it need only be implemented if the filesystem can perform
1426 that action more efficiently.
1427 typedef int Tcl_FSCopyDirectoryProc(
1429 Tcl_Obj *srcPathPtr,
1430 Tcl_Obj *destPathPtr,
1431 Tcl_Obj **errorPtr);
1432 The return value is a standard Tcl result indicating whether an error
1434 occurred in the copying process. If an error does occur, the name of
1435 the file or directory which caused the error should be placed in
1436 errorPtr. Note that, destPathPtr is the name of the directory-name
1437 which should become the mirror-image of srcPathPtr. It is not the name
1438 of a directory into which srcPathPtr should be copied (i.e. the func‐
1439 tion is much simpler than the Tcl level file copy subcommand).
1440 Finally, if the filesystem determines it cannot support the directory
1441 copy action, calling Tcl_SetErrno(EXDEV) and returning a non-TCL_OK
1442 result will tell Tcl to use its standard fallback mechanisms.
1443 LOADFILEPROC
1445 Function to process a Tcl_FSLoadFile call. If not implemented, Tcl
1446 will fall back on a copy to native-temp followed by a Tcl_FSLoadFile on
1447 that temporary copy. Therefore it need only be implemented if the
1448 filesystem can load code directly, or it can be implemented simply to
1449 return TCL_ERROR to disable load functionality in this filesystem
1450 entirely.
1451 typedef int Tcl_FSLoadFileProc(
1453 Tcl_Interp *interp,
1454 Tcl_Obj *pathPtr,
1455 Tcl_LoadHandle *handlePtr,
1456 Tcl_FSUnloadFileProc *unloadProcPtr);
1457 Returns a standard Tcl completion code. If an error occurs, an error
1459 message is left in the interp's result. The function dynamically loads
1460 a binary code file into memory. On a successful load, the handlePtr
1461 should be filled with a token for the dynamically loaded file, and the
1462 unloadProcPtr should be filled in with the address of a procedure. The
1463 unload procedure will be called with the given Tcl_LoadHandle as its
1464 only parameter when Tcl needs to unload the file. For example, for the
1465 native filesystem, the Tcl_LoadHandle returned is currently a token
1466 which can be used in the private TclpFindSymbol to access functions in
1467 the new code. Each filesystem is free to define the Tcl_LoadHandle as
1468 it requires. Finally, if the filesystem determines it cannot support
1469 the file load action, calling Tcl_SetErrno(EXDEV) and returning a non-
1470 TCL_OK result will tell Tcl to use its standard fallback mechanisms.
1471 UNLOADFILEPROC
1473 Function to unload a previously successfully loaded file. If load was
1474 implemented, then this should also be implemented, if there is any
1475 cleanup action required.
1476 typedef void Tcl_FSUnloadFileProc(
1478 Tcl_LoadHandle loadHandle);
1479 GETCWDPROC
1481 Function to process a Tcl_FSGetCwd call. Most filesystems need not
1482 implement this. It will usually only be called once, if getcwd is
1483 called before chdir. May be NULL.
1484 typedef Tcl_Obj* Tcl_FSGetCwdProc(
1486 Tcl_Interp *interp);
1487 If the filesystem supports a native notion of a current working direc‐
1489 tory (which might perhaps change independent of Tcl), this function
1490 should return that cwd as the result, or NULL if the current directory
1491 could not be determined (e.g. the user does not have appropriate per‐
1492 missions on the cwd directory). If NULL is returned, an error message
1493 is left in the interp's result.
1494 CHDIRPROC
1496 Function to process a Tcl_FSChdir call. If filesystems do not imple‐
1497 ment this, it will be emulated by a series of directory access checks.
1498 Otherwise, virtual filesystems which do implement it need only respond
1499 with a positive return result if the pathPtr is a valid, accessible
1500 directory in their filesystem. They need not remember the result,
1501 since that will be automatically remembered for use by Tcl_FSGetCwd.
1502 Real filesystems should carry out the correct action (i.e. call the
1503 correct system chdir API).
1504 typedef int Tcl_FSChdirProc(
1506 Tcl_Obj *pathPtr);
1507 The Tcl_FSChdirProc changes the applications current working directory
1509 to the value specified in pathPtr. The function returns -1 on error or
1510 0 on success.
1511
1513 cd(n), file(n), load(n), open(n), pwd(n), unload(n)
1514
1516 stat, access, filesystem, vfs, virtual
1517Tcl 8.4 Filesystem(3)