2 '\" Copyright (c) 2001 Vincent Darley
3 '\" Copyright (c) 2008-2010 Donal K. Fellows
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSEvalFileEx, Tcl_FSLoadFile, Tcl_FSUnloadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_GetAccessTimeFromStat, Tcl_GetBlockSizeFromStat, Tcl_GetBlocksFromStat, Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat, Tcl_GetFSDeviceFromStat, Tcl_GetFSInodeFromStat, Tcl_GetGroupIdFromStat, Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTimeFromStat, Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, Tcl_AllocStatBuf \- procedures to interact with any filesystem
281 \fB#include <tcl.h>\fR
284 \fBTcl_FSRegister\fR(\fIclientData, fsPtr\fR)
287 \fBTcl_FSUnregister\fR(\fIfsPtr\fR)
290 \fBTcl_FSData\fR(\fIfsPtr\fR)
293 \fBTcl_FSMountsChanged\fR(\fIfsPtr\fR)
295 const Tcl_Filesystem *
296 \fBTcl_FSGetFileSystemForPath\fR(\fIpathPtr\fR)
299 \fBTcl_FSGetPathType\fR(\fIpathPtr\fR)
302 \fBTcl_FSCopyFile\fR(\fIsrcPathPtr, destPathPtr\fR)
305 \fBTcl_FSCopyDirectory\fR(\fIsrcPathPtr, destPathPtr, errorPtr\fR)
308 \fBTcl_FSCreateDirectory\fR(\fIpathPtr\fR)
311 \fBTcl_FSDeleteFile\fR(\fIpathPtr\fR)
314 \fBTcl_FSRemoveDirectory\fR(\fIpathPtr, int recursive, errorPtr\fR)
317 \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR)
320 \fBTcl_FSListVolumes\fR(\fIvoid\fR)
323 \fBTcl_FSEvalFileEx\fR(\fIinterp, pathPtr, encodingName\fR)
326 \fBTcl_FSEvalFile\fR(\fIinterp, pathPtr\fR)
329 \fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
330 loadHandlePtr, unloadProcPtr\fR)
334 \fBTcl_FSUnloadFile\fR(\fIinterp, loadHandle\fR)
338 \fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR)
341 \fBTcl_FSLink\fR(\fIlinkNamePtr, toPtr, linkAction\fR)
344 \fBTcl_FSLstat\fR(\fIpathPtr, statPtr\fR)
347 \fBTcl_FSUtime\fR(\fIpathPtr, tval\fR)
350 \fBTcl_FSFileAttrsGet\fR(\fIinterp, int index, pathPtr, objPtrRef\fR)
353 \fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR)
356 \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR)
359 \fBTcl_FSStat\fR(\fIpathPtr, statPtr\fR)
362 \fBTcl_FSAccess\fR(\fIpathPtr, mode\fR)
365 \fBTcl_FSOpenFileChannel\fR(\fIinterp, pathPtr, modeString, permissions\fR)
368 \fBTcl_FSGetCwd\fR(\fIinterp\fR)
371 \fBTcl_FSChdir\fR(\fIpathPtr\fR)
374 \fBTcl_FSPathSeparator\fR(\fIpathPtr\fR)
377 \fBTcl_FSJoinPath\fR(\fIlistObj, elements\fR)
380 \fBTcl_FSSplitPath\fR(\fIpathPtr, lenPtr\fR)
383 \fBTcl_FSEqualPaths\fR(\fIfirstPtr, secondPtr\fR)
386 \fBTcl_FSGetNormalizedPath\fR(\fIinterp, pathPtr\fR)
389 \fBTcl_FSJoinToPath\fR(\fIbasePtr, objc, objv\fR)
392 \fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR)
395 \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR)
398 \fBTcl_FSGetTranslatedPath\fR(\fIinterp, pathPtr\fR)
401 \fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR)
404 \fBTcl_FSNewNativePath\fR(\fIfsPtr, clientData\fR)
407 \fBTcl_FSGetNativePath\fR(\fIpathPtr\fR)
410 \fBTcl_FSFileSystemInfo\fR(\fIpathPtr\fR)
413 \fBTcl_AllocStatBuf\fR()
417 \fBTcl_GetAccessTimeFromStat\fR(\fIstatPtr\fR)
420 \fBTcl_GetBlockSizeFromStat\fR(\fIstatPtr\fR)
423 \fBTcl_GetBlocksFromStat\fR(\fIstatPtr\fR)
426 \fBTcl_GetChangeTimeFromStat\fR(\fIstatPtr\fR)
429 \fBTcl_GetDeviceTypeFromStat\fR(\fIstatPtr\fR)
432 \fBTcl_GetFSDeviceFromStat\fR(\fIstatPtr\fR)
435 \fBTcl_GetFSInodeFromStat\fR(\fIstatPtr\fR)
438 \fBTcl_GetGroupIdFromStat\fR(\fIstatPtr\fR)
441 \fBTcl_GetLinkCountFromStat\fR(\fIstatPtr\fR)
444 \fBTcl_GetModeFromStat\fR(\fIstatPtr\fR)
447 \fBTcl_GetModificationTimeFromStat\fR(\fIstatPtr\fR)
450 \fBTcl_GetSizeFromStat\fR(\fIstatPtr\fR)
453 \fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR)
456 .AS Tcl_GlobTypeData **srcPathPtr out
457 .AP "const Tcl_Filesystem" *fsPtr in
458 Points to a structure containing the addresses of procedures that
459 can be called to perform the various filesystem operations.
460 .AP Tcl_Obj *pathPtr in
461 The path represented by this value is used for the operation in
462 question. If the value does not already have an internal \fBpath\fR
463 representation, it will be converted to have one.
464 .AP Tcl_Obj *srcPathPtr in
465 As for \fIpathPtr\fR, but used for the source file for a copy or
467 .AP Tcl_Obj *destPathPtr in
468 As for \fIpathPtr\fR, but used for the destination filename for a copy or
470 .AP "const char" *encodingName in
471 The encoding of the data stored in the
472 file identified by \fIpathPtr\fR and to be evaluated.
473 .AP "const char" *pattern in
474 Only files or directories matching this pattern will be returned.
475 .AP Tcl_GlobTypeData *types in
476 Only files or directories matching the type descriptions contained in
477 this structure will be returned. This parameter may be NULL.
478 .AP Tcl_Interp *interp in
479 Interpreter to use either for results, evaluation, or reporting error
481 .AP ClientData clientData in
482 The native description of the path value to create.
483 .AP Tcl_Obj *firstPtr in
484 The first of two path values to compare. The value may be converted
486 .AP Tcl_Obj *secondPtr in
487 The second of two path values to compare. The value may be converted
489 .AP Tcl_Obj *listObj in
490 The list of path elements to operate on with a \fBjoin\fR operation.
492 If non-negative, the number of elements in the \fIlistObj\fR which should
493 be joined together. If negative, then all elements are joined.
494 .AP Tcl_Obj **errorPtr out
495 In the case of an error, filled with a value containing the name of
496 the file which caused an error in the various copy/rename operations.
497 .AP Tcl_Obj **objPtrRef out
498 Filled with a value containing the result of the operation.
499 .AP Tcl_Obj *resultPtr out
500 Pre-allocated value in which to store (using
501 \fBTcl_ListObjAppendElement\fR) the list of
502 files or directories which are successfully matched.
504 Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. R_OK,
505 W_OK and X_OK request checking whether the file exists and has read,
506 write and execute permissions, respectively. F_OK just requests
507 checking for the existence of the file.
508 .AP Tcl_StatBuf *statPtr out
509 The structure that contains the result of a stat or lstat operation.
510 .AP "const char" *sym1 in
511 Name of a procedure to look up in the file's symbol table
512 .AP "const char" *sym2 in
513 Name of a procedure to look up in the file's symbol table
514 .AP Tcl_PackageInitProc **proc1Ptr out
515 Filled with the init function for this code.
516 .AP Tcl_PackageInitProc **proc2Ptr out
517 Filled with the safe-init function for this code.
518 .AP ClientData *clientDataPtr out
519 Filled with the clientData value to pass to this code's unload
520 function when it is called.
521 .AP Tcl_LoadHandle *loadHandlePtr out
522 Filled with an abstract token representing the loaded file.
523 .AP Tcl_FSUnloadFileProc **unloadProcPtr out
524 Filled with the function to use to unload this piece of code.
525 .AP Tcl_LoadHandle loadHandle in
526 Handle to the loaded library to be unloaded.
528 The access and modification times in this structure are read and
529 used to set those values for a given file.
530 .AP "const char" *modeString in
531 Specifies how the file is to be accessed. May have any of the values
532 allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
533 .AP int permissions in
534 POSIX-style permission flags such as 0644. If a new file is created, these
535 permissions will be set on the created file.
537 If non-NULL, filled with the number of elements in the split path.
538 .AP Tcl_Obj *basePtr in
539 The base path on to which to join the given elements. May be NULL.
541 The number of elements in \fIobjv\fR.
542 .AP "Tcl_Obj *const" objv[] in
543 The elements to join to the given base path.
544 .AP Tcl_Obj *linkNamePtr in
545 The name of the link to be created or read.
546 .AP Tcl_Obj *toPtr in
547 What the link called \fIlinkNamePtr\fR should be linked to, or NULL if
548 the symbolic link specified by \fIlinkNamePtr\fR is to be read.
549 .AP int linkAction in
550 OR-ed combination of flags indicating what kind of link should be
551 created (will be ignored if \fItoPtr\fR is NULL). Valid bits to set
552 are \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR.
553 When both flags are set and the underlying filesystem can do either,
554 symbolic links are preferred.
558 There are several reasons for calling the \fBTcl_FS\fR API functions
559 (e.g.\ \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR)
560 rather than calling system level functions like \fBaccess\fR and
561 \fBstat\fR directly. First, they will work cross-platform, so an
562 extension which calls them should work unmodified on Unix and
563 Windows. Second, the Windows implementation of some of these functions
564 fixes some bugs in the system level calls. Third, these function calls
566 .QW "Utf to platform-native"
567 path conversions which may be
568 required (and may cache the results of such conversions for greater
569 efficiency on subsequent calls). Fourth, and perhaps most importantly,
570 all of these functions are
571 .QW "virtual filesystem aware" .
572 Any virtual filesystem (VFS for short) which has been registered (through
573 \fBTcl_FSRegister\fR) may reroute file access to alternative
574 media or access methods. This means that all of these functions (and
575 therefore the corresponding \fBfile\fR, \fBglob\fR, \fBpwd\fR, \fBcd\fR,
576 \fBopen\fR, etc.\ Tcl commands) may be operate on
579 native files in the native filesystem. This also means that any Tcl
580 extension which accesses the filesystem (FS for short) through this API is
582 .QW "virtual filesystem aware" .
583 Of course, if an extension
584 accesses the native filesystem directly (through platform-specific
585 APIs, for example), then Tcl cannot intercept such calls.
587 If appropriate VFSes have been registered, the
590 examples, be remote (e.g.\ situated on a remote ftp server) or archived
591 (e.g.\ lying inside a .zip archive). Such registered filesystems provide
592 a lookup table of functions to implement all or some of the functionality
593 listed here. Finally, the \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR calls
594 abstract away from what the
597 declared to be, allowing the same code to be used both on systems with
598 and systems without support for files larger than 2GB in size.
600 The \fBTcl_FS\fR API is \fBTcl_Obj\fR-ified and may cache internal
601 representations and other path-related strings (e.g.\ the current working
602 directory). One side-effect of this is that one must not pass in values
603 with a reference count of zero to any of these functions. If such calls were
604 handled, they might result
605 in memory leaks (under some circumstances, the filesystem code may wish
606 to retain a reference to the passed in value, and so one must not assume
607 that after any of these calls return, the value still has a reference count of
608 zero - it may have been incremented) or in a direct segmentation fault
609 (or other memory access error)
610 due to the value being freed part way through the complex value
611 manipulation required to ensure that the path is fully normalized and
612 absolute for filesystem determination. The practical lesson to learn
616 Tcl_Obj *path = Tcl_NewStringObj(...);
617 Tcl_FS\fIWhatever\fR(path);
618 Tcl_DecrRefCount(path);
621 is wrong, and may cause memory errors. The \fIpath\fR must have its
622 reference count incremented before passing it in, or
623 decrementing it. For this reason, values with a reference count of zero are
624 considered not to be valid filesystem paths and calling any Tcl_FS API
625 function with such a value will result in no action being taken.
626 .SS "FS API FUNCTIONS"
627 \fBTcl_FSCopyFile\fR attempts to copy the file given by \fIsrcPathPtr\fR to the
628 path name given by \fIdestPathPtr\fR. If the two paths given lie in the same
629 filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
632 function is called (if it is non-NULL).
633 Otherwise the function returns -1 and sets the \fBerrno\fR global C
636 POSIX error code (which signifies a
637 .QW "cross-domain link" ).
639 \fBTcl_FSCopyDirectory\fR attempts to copy the directory given by \fIsrcPathPtr\fR to the
640 path name given by \fIdestPathPtr\fR. If the two paths given lie in the same
641 filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
644 function is called (if it is non-NULL).
645 Otherwise the function returns -1 and sets the \fBerrno\fR global C
648 POSIX error code (which signifies a
649 .QW "cross-domain link" ).
651 \fBTcl_FSCreateDirectory\fR attempts to create the directory given by
652 \fIpathPtr\fR by calling the owning filesystem's
653 .QW "create directory"
656 \fBTcl_FSDeleteFile\fR attempts to delete the file given by
657 \fIpathPtr\fR by calling the owning filesystem's
661 \fBTcl_FSRemoveDirectory\fR attempts to remove the directory given by
662 \fIpathPtr\fR by calling the owning filesystem's
663 .QW "remove directory"
666 \fBTcl_FSRenameFile\fR attempts to rename the file or directory given by
667 \fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths
668 given lie in the same filesystem (according to
669 \fBTcl_FSGetFileSystemForPath\fR) then that filesystem's
671 function is called (if it is non-NULL). Otherwise the function returns -1
672 and sets the \fBerrno\fR global C variable to the
674 POSIX error code (which signifies a
675 .QW "cross-domain link" ).
677 \fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL
679 function and asks them to return their list of root volumes. It
680 accumulates the return values in a list which is returned to the
681 caller (with a reference count of 0).
683 \fBTcl_FSEvalFileEx\fR reads the file given by \fIpathPtr\fR using
684 the encoding identified by \fIencodingName\fR and evaluates
685 its contents as a Tcl script. It returns the same information as
687 If \fIencodingName\fR is NULL, the system encoding is used for
688 reading the file contents.
689 If the file could not be read then a Tcl error is returned to describe
690 why the file could not be read.
691 The eofchar for files is
693 (^Z) for all platforms.
696 in code for string comparison, you can use
700 which will be safely substituted by the Tcl interpreter into
702 \fBTcl_FSEvalFile\fR is a simpler version of
703 \fBTcl_FSEvalFileEx\fR that always uses the system encoding
704 when reading the file.
706 \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
707 returns the addresses of two procedures within that file, if they are
708 defined. The appropriate function for the filesystem to which \fIpathPtr\fR
709 belongs will be called. If that filesystem does not implement this
710 function (most virtual filesystems will not, because of OS limitations
711 in dynamically loading binary code), Tcl will attempt to copy the file
712 to a temporary directory and load that temporary file.
714 \fBTcl_FSUnloadFile\fR reverses the operation, asking for the library
715 indicated by the \fIloadHandle\fR to be removed from the process. Note that,
716 unlike with the \fBunload\fR command, this does not give the library any
717 opportunity to clean up.
720 Both the above functions return a standard Tcl completion code. If an error
721 occurs, an error message is left in the \fIinterp\fR's result.
724 The token provided via the variable indicated by \fIloadHandlePtr\fR may be
725 used with \fBTcl_FindSymbol\fR.
728 \fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a
729 directory for all files which match a given pattern. The appropriate
730 function for the filesystem to which \fIpathPtr\fR belongs will be called.
732 The return value is a standard Tcl result indicating whether an error
733 occurred in globbing. Error messages are placed in interp (unless
734 interp is NULL, which is allowed), but good results are placed in the
737 Note that the \fBglob\fR code implements recursive patterns internally, so
738 this function will only ever be passed simple patterns, which can be
739 matched using the logic of \fBstring match\fR. To handle recursion, Tcl
740 will call this function frequently asking only for directories to be
741 returned. A special case of being called with a NULL pattern indicates
742 that the path needs to be checked only for the correct type.
744 \fBTcl_FSLink\fR replaces the library version of \fBreadlink\fR, and
745 extends it to support the creation of links. The appropriate function
746 for the filesystem to which \fIlinkNamePtr\fR belongs will be called.
748 If the \fItoPtr\fR is NULL, a
750 action is performed. The result
751 is a Tcl_Obj specifying the contents of the symbolic link given by
752 \fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned
753 by the caller, which should call \fBTcl_DecrRefCount\fR when the result is no
754 longer needed. If the \fItoPtr\fR is not NULL, Tcl should create a link
755 of one of the types passed in in the \fIlinkAction\fR flag. This flag is
756 an ORed combination of \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR.
757 Where a choice exists (i.e.\ more than one flag is passed in), the Tcl
758 convention is to prefer symbolic links. When a link is successfully
759 created, the return value should be \fItoPtr\fR (which is therefore
760 already owned by the caller). If unsuccessful, NULL is returned.
762 \fBTcl_FSLstat\fR fills the \fITcl_StatBuf\fR structure \fIstatPtr\fR with
763 information about the specified file. You do not need any access rights to the
764 file to get this information but you need search rights to all
765 directories named in the path leading to the file. The \fITcl_StatBuf\fR
766 structure includes info regarding device, inode (always 0 on Windows),
767 privilege mode, nlink (always 1 on Windows), user id (always 0 on
768 Windows), group id (always 0 on Windows), rdev (same as device on
769 Windows), size, last access time, last modification time, and
770 last metadata change time.
771 See \fBPORTABLE STAT RESULT API\fR for a description of how to write
772 portable code to allocate and access the \fITcl_StatBuf\fR structure.
774 If \fIpath\fR exists, \fBTcl_FSLstat\fR returns 0 and the stat structure
775 is filled with data. Otherwise, -1 is returned, and no stat info is
778 \fBTcl_FSUtime\fR replaces the library version of utime.
780 This returns 0 on success and -1 on error (as per the \fButime\fR
781 documentation). If successful, the function
786 values of the file given.
788 \fBTcl_FSFileAttrsGet\fR implements read access for the hookable \fBfile
789 attributes\fR subcommand. The appropriate function for the filesystem to
790 which \fIpathPtr\fR belongs will be called.
792 If the result is \fBTCL_OK\fR, then a value was placed in
793 \fIobjPtrRef\fR, which
794 will only be temporarily valid (unless \fBTcl_IncrRefCount\fR is called).
796 \fBTcl_FSFileAttrsSet\fR implements write access for the hookable \fBfile
797 attributes\fR subcommand. The appropriate function for the filesystem to
798 which \fIpathPtr\fR belongs will be called.
800 \fBTcl_FSFileAttrStrings\fR implements part of the hookable \fBfile
801 attributes\fR subcommand. The appropriate function for the filesystem
802 to which \fIpathPtr\fR belongs will be called.
804 The called procedure may either return an array of strings, or may
805 instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR. Tcl
806 will take that list and first increment its reference count before using it.
807 On completion of that use, Tcl will decrement its reference count. Hence if
808 the list should be disposed of by Tcl when done, it should have a
809 reference count of zero, and if the list should not be disposed of, the
810 filesystem should ensure it retains a reference count to the value.
812 \fBTcl_FSAccess\fR checks whether the process would be allowed to read,
813 write or test for existence of the file (or other filesystem object)
814 whose name is \fIpathname\fR. If \fIpathname\fR is a symbolic link on Unix,
815 then permissions of the file referred by this symbolic link are
818 On success (all requested permissions granted), zero is returned. On
819 error (at least one bit in mode asked for a permission that is denied,
820 or some other error occurred), -1 is returned.
822 \fBTcl_FSStat\fR fills the \fITcl_StatBuf\fR structure \fIstatPtr\fR with
823 information about the specified file. You do not need any access rights to the
824 file to get this information but you need search rights to all
825 directories named in the path leading to the file. The \fITcl_StatBuf\fR
826 structure includes info regarding device, inode (always 0 on Windows),
827 privilege mode, nlink (always 1 on Windows), user id (always 0 on
828 Windows), group id (always 0 on Windows), rdev (same as device on
829 Windows), size, last access time, last modification time, and
830 last metadata change time.
831 See \fBPORTABLE STAT RESULT API\fR for a description of how to write
832 portable code to allocate and access the \fITcl_StatBuf\fR structure.
834 If \fIpath\fR exists, \fBTcl_FSStat\fR returns 0 and the stat structure
835 is filled with data. Otherwise, -1 is returned, and no stat info is
838 \fBTcl_FSOpenFileChannel\fR opens a file specified by \fIpathPtr\fR and
839 returns a channel handle that can be used to perform input and output on
840 the file. This API is modeled after the \fBfopen\fR procedure of
841 the Unix standard I/O library.
842 The syntax and meaning of all arguments is similar to those
843 given in the Tcl \fBopen\fR command when opening a file.
844 If an error occurs while opening the channel, \fBTcl_FSOpenFileChannel\fR
845 returns NULL and records a POSIX error code that can be
846 retrieved with \fBTcl_GetErrno\fR.
847 In addition, if \fIinterp\fR is non-NULL, \fBTcl_FSOpenFileChannel\fR
848 leaves an error message in \fIinterp\fR's result after any error.
850 The newly created channel is not registered in the supplied interpreter; to
851 register it, use \fBTcl_RegisterChannel\fR.
852 If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
853 previously closed, the act of creating the new channel also assigns it as a
854 replacement for the standard channel.
856 \fBTcl_FSGetCwd\fR replaces the library version of \fBgetcwd\fR.
858 It returns the Tcl library's current working directory. This may be
859 different to the native platform's working directory, which happens when
860 the current working directory is not in the native filesystem.
862 The result is a pointer to a Tcl_Obj specifying the current directory,
863 or NULL if the current directory could not be determined. If NULL is
864 returned, an error message is left in the \fIinterp\fR's result.
866 The result already has its reference count incremented for the caller. When
867 it is no longer needed, that reference count should be decremented. This is
868 needed for thread-safety purposes, to allow multiple threads to access
869 this and related functions, while ensuring the results are always
872 \fBTcl_FSChdir\fR replaces the library version of \fBchdir\fR. The path is
873 normalized and then passed to the filesystem which claims it. If that
874 filesystem does not implement this function, Tcl will fallback to a
875 combination of \fBstat\fR and \fBaccess\fR to check whether the directory
876 exists and has appropriate permissions.
878 For results, see \fBchdir\fR documentation. If successful, we keep a
879 record of the successful path in \fIcwdPathPtr\fR for subsequent calls to
882 \fBTcl_FSPathSeparator\fR returns the separator character to be used for
883 most specific element of the path specified by \fIpathPtr\fR (i.e.\ the last
886 The separator is returned as a Tcl_Obj containing a string of length
887 1. If the path is invalid, NULL is returned.
889 \fBTcl_FSJoinPath\fR takes the given Tcl_Obj, which must be a valid
890 list (which is allowed to have a reference count of zero), and returns the path
891 value given by considering the first \fIelements\fR elements as valid path
892 segments (each path segment may be a complete path, a partial path or
893 just a single possible directory or file name). If any path segment is
894 actually an absolute path, then all prior path segments are discarded.
895 If \fIelements\fR is less than 0, we use the entire list.
897 It is possible that the returned value is actually an element
898 of the given list, so the caller should be careful to increment the
899 reference count of the result before freeing the list.
901 The returned value, typically with a reference count of zero (but it
903 under some conditions), contains the joined path. The caller must
904 add a reference count to the value before using it. In particular, the
905 returned value could be an element of the given list, so freeing the
906 list might free the value prematurely if no reference count has been taken.
907 If the number of elements is zero, then the returned value will be
908 an empty-string Tcl_Obj.
910 \fBTcl_FSSplitPath\fR takes the given Tcl_Obj, which should be a valid path,
911 and returns a Tcl list value containing each segment of that path as
913 It returns a list value with a reference count of zero. If the
914 passed in \fIlenPtr\fR is non-NULL, the variable it points to will be
915 updated to contain the number of elements in the returned list.
917 \fBTcl_FSEqualPaths\fR tests whether the two paths given represent the same
919 It returns 1 if the paths are equal, and 0 if they are different. If
920 either path is NULL, 0 is always returned.
922 \fBTcl_FSGetNormalizedPath\fR this important function attempts to extract
923 from the given Tcl_Obj a unique normalized path representation, whose
924 string value can be used as a unique identifier for the file.
926 It returns the normalized path value, owned by Tcl, or NULL if the path
927 was invalid or could otherwise not be successfully converted.
928 Extraction of absolute, normalized paths is very efficient (because the
929 filesystem operates on these representations internally), although the
930 result when the filesystem contains numerous symbolic links may not be
931 the most user-friendly version of a path. The return value is owned by
932 Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR passed in
933 (unless that is a relative path, in which case the normalized path
934 value may be freed any time the cwd changes) - the caller can of
935 course increment the reference count if it wishes to maintain a copy for longer.
937 \fBTcl_FSJoinToPath\fR takes the given value, which should usually be a
938 valid path or NULL, and joins onto it the array of paths segments
941 Returns a value, typically with reference count of zero (but it could be shared
942 under some conditions), containing the joined path. The caller must
943 add a reference count to the value before using it. If any of the values
944 passed into this function (\fIpathPtr\fR or \fIpath\fR elements) have
946 of zero, they will be freed when this function returns.
948 \fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid
949 Tcl path type, taking account of the fact that the cwd may have changed
950 even if this value is already supposedly of the correct type.
951 The filename may begin with
953 (to indicate current user's home directory) or
955 (to indicate any user's home directory).
957 If the conversion succeeds (i.e.\ the value is a valid path in one of
958 the current filesystems), then \fBTCL_OK\fR is returned. Otherwise
959 \fBTCL_ERROR\fR is returned, and an error message may
960 be left in the interpreter.
962 \fBTcl_FSGetInternalRep\fR extracts the internal representation of a given
963 path value, in the given filesystem. If the path value belongs to a
964 different filesystem, we return NULL. If the internal representation is
965 currently NULL, we attempt to generate it, by calling the filesystem's
966 \fBTcl_FSCreateInternalRepProc\fR.
968 Returns NULL or a valid internal path representation. This internal
969 representation is cached, so that repeated calls to this function will
970 not require additional conversions.
972 \fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path
973 from the given Tcl_Obj.
975 If the translation succeeds (i.e.\ the value is a valid path), then it is
976 returned. Otherwise NULL will be returned, and an error message may be
977 left in the interpreter. A
979 path is one which contains no
983 sequences (these have been expanded to their current
984 representation in the filesystem). The value returned is owned by the
985 caller, which must store it or call \fBTcl_DecrRefCount\fR to ensure memory is
986 freed. This function is of little practical use, and
987 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
988 better functions to use for most purposes.
990 \fBTcl_FSGetTranslatedStringPath\fR does the same as
991 \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
992 The string returned is dynamically allocated and owned by the caller,
993 which must store it or call \fBckfree\fR to ensure it is freed. Again,
994 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
995 better functions to use for most purposes.
997 \fBTcl_FSNewNativePath\fR performs something like the reverse of the
998 usual obj->path->nativerep conversions. If some code retrieves a path
999 in native form (from, e.g.\ \fBreadlink\fR or a native dialog), and that path
1000 is to be used at the Tcl level, then calling this function is an
1001 efficient way of creating the appropriate path value type.
1003 The resulting value is a pure
1005 value, which will only receive
1006 a UTF-8 string representation if that is required by some Tcl code.
1008 \fBTcl_FSGetNativePath\fR is for use by the Win/Unix native
1009 filesystems, so that they can easily retrieve the native (char* or
1010 TCHAR*) representation of a path. This function is a convenience
1011 wrapper around \fBTcl_FSGetInternalRep\fR. It may be desirable in the
1012 future to have non-string-based native representations (for example,
1013 on MacOSX, a representation using a fileSpec of FSRef structure would
1014 probably be more efficient). On Windows a full Unicode representation
1015 would allow for paths of unlimited length. Currently the representation
1016 is simply a character string which may contain either the relative path
1017 or a complete, absolute normalized path in the native encoding (complex
1018 conditions dictate which of these will be provided, so neither can be
1019 relied upon, unless the path is known to be absolute). If you need a
1020 native path which must be absolute, then you should ask for the native
1021 version of a normalized path. If for some reason a non-absolute,
1022 non-normalized version of the path is needed, that must be constructed
1023 separately (e.g.\ using \fBTcl_FSGetTranslatedPath\fR).
1025 The native representation is cached so that repeated calls to this
1026 function will not require additional conversions. The return value is
1027 owned by Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR
1028 passed in (unless that is a relative path, in which case the native
1029 representation may be freed any time the cwd changes).
1031 \fBTcl_FSFileSystemInfo\fR returns a list of two elements. The first
1032 element is the name of the filesystem (e.g.
1038 perhaps), and the second is the particular type of the
1039 given path within that filesystem (which is filesystem dependent). The
1040 second element may be empty if the filesystem does not provide a
1041 further categorization of files.
1043 A valid list value is returned, unless the path value is not
1044 recognized, when NULL will be returned.
1046 \fBTcl_FSGetFileSystemForPath\fR returns a pointer to the
1047 \fBTcl_Filesystem\fR which accepts this path as valid.
1049 If no filesystem will accept the path, NULL is returned.
1051 \fBTcl_FSGetPathType\fR determines whether the given path is relative
1052 to the current directory, relative to the current volume, or
1055 It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or
1056 \fBTCL_PATH_VOLUME_RELATIVE\fR
1057 .SS "PORTABLE STAT RESULT API"
1059 \fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system heap (which
1060 may be deallocated by being passed to \fBckfree\fR). This allows extensions to
1061 invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the
1062 size of the buffer. That in turn depends on the flags used to build Tcl.
1065 The portable fields of a \fITcl_StatBuf\fR may be read using the following
1066 functions, each of which returns the value of the corresponding field listed
1067 in the table below. Note that on some platforms there may be other fields in
1068 the \fITcl_StatBuf\fR as it is an alias for a suitable system structure, but
1069 only the portable ones are made available here. See your system documentation
1070 for a full description of these fields.
1072 .ta \w'\fBTcl_GetModificationTimeFromStat\fR\0\0\0\0'u
1073 \fIAccess Function\fR \fIField\fR
1074 \fBTcl_GetFSDeviceFromStat\fR st_dev
1075 \fBTcl_GetFSInodeFromStat\fR st_ino
1076 \fBTcl_GetModeFromStat\fR st_mode
1077 \fBTcl_GetLinkCountFromStat\fR st_nlink
1078 \fBTcl_GetUserIdFromStat\fR st_uid
1079 \fBTcl_GetGroupIdFromStat\fR st_gid
1080 \fBTcl_GetDeviceTypeFromStat\fR st_rdev
1081 \fBTcl_GetAccessTimeFromStat\fR st_atime
1082 \fBTcl_GetModificationTimeFromStat\fR st_mtime
1083 \fBTcl_GetChangeTimeFromStat\fR st_ctime
1084 \fBTcl_GetSizeFromStat\fR st_size
1085 \fBTcl_GetBlocksFromStat\fR st_blocks
1086 \fBTcl_GetBlockSizeFromStat\fR st_blksize
1089 .SH "THE VIRTUAL FILESYSTEM API"
1091 A filesystem provides a \fBTcl_Filesystem\fR structure that contains
1092 pointers to functions that implement the various operations on a
1093 filesystem; these operations are invoked as needed by the generic
1094 layer, which generally occurs through the functions listed above.
1096 The \fBTcl_Filesystem\fR structures are manipulated using the following
1099 \fBTcl_FSRegister\fR takes a pointer to a filesystem structure and an
1100 optional piece of data to associated with that filesystem. On calling
1101 this function, Tcl will attach the filesystem to the list of known
1102 filesystems, and it will become fully functional immediately. Tcl does
1103 not check if the same filesystem is registered multiple times (and in
1104 general that is not a good thing to do). \fBTCL_OK\fR will be returned.
1106 \fBTcl_FSUnregister\fR removes the given filesystem structure from
1107 the list of known filesystems, if it is known, and returns \fBTCL_OK\fR. If
1108 the filesystem is not currently registered, \fBTCL_ERROR\fR is returned.
1110 \fBTcl_FSData\fR will return the ClientData associated with the given
1111 filesystem, if that filesystem is registered. Otherwise it will
1114 \fBTcl_FSMountsChanged\fR is used to inform the Tcl's core that
1115 the set of mount points for the given (already registered) filesystem
1116 have changed, and that cached file representations may therefore no
1118 .SS "THE TCL_FILESYSTEM STRUCTURE"
1120 The \fBTcl_Filesystem\fR structure contains the following fields:
1123 typedef struct Tcl_Filesystem {
1124 const char *\fItypeName\fR;
1125 int \fIstructureLength\fR;
1126 Tcl_FSVersion \fIversion\fR;
1127 Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR;
1128 Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR;
1129 Tcl_FSFreeInternalRepProc *\fIfreeInternalRepProc\fR;
1130 Tcl_FSInternalToNormalizedProc *\fIinternalToNormalizedProc\fR;
1131 Tcl_FSCreateInternalRepProc *\fIcreateInternalRepProc\fR;
1132 Tcl_FSNormalizePathProc *\fInormalizePathProc\fR;
1133 Tcl_FSFilesystemPathTypeProc *\fIfilesystemPathTypeProc\fR;
1134 Tcl_FSFilesystemSeparatorProc *\fIfilesystemSeparatorProc\fR;
1135 Tcl_FSStatProc *\fIstatProc\fR;
1136 Tcl_FSAccessProc *\fIaccessProc\fR;
1137 Tcl_FSOpenFileChannelProc *\fIopenFileChannelProc\fR;
1138 Tcl_FSMatchInDirectoryProc *\fImatchInDirectoryProc\fR;
1139 Tcl_FSUtimeProc *\fIutimeProc\fR;
1140 Tcl_FSLinkProc *\fIlinkProc\fR;
1141 Tcl_FSListVolumesProc *\fIlistVolumesProc\fR;
1142 Tcl_FSFileAttrStringsProc *\fIfileAttrStringsProc\fR;
1143 Tcl_FSFileAttrsGetProc *\fIfileAttrsGetProc\fR;
1144 Tcl_FSFileAttrsSetProc *\fIfileAttrsSetProc\fR;
1145 Tcl_FSCreateDirectoryProc *\fIcreateDirectoryProc\fR;
1146 Tcl_FSRemoveDirectoryProc *\fIremoveDirectoryProc\fR;
1147 Tcl_FSDeleteFileProc *\fIdeleteFileProc\fR;
1148 Tcl_FSCopyFileProc *\fIcopyFileProc\fR;
1149 Tcl_FSRenameFileProc *\fIrenameFileProc\fR;
1150 Tcl_FSCopyDirectoryProc *\fIcopyDirectoryProc\fR;
1151 Tcl_FSLstatProc *\fIlstatProc\fR;
1152 Tcl_FSLoadFileProc *\fIloadFileProc\fR;
1153 Tcl_FSGetCwdProc *\fIgetCwdProc\fR;
1154 Tcl_FSChdirProc *\fIchdirProc\fR;
1155 } \fBTcl_Filesystem\fR;
1158 Except for the first three fields in this structure which contain
1159 simple data elements, all entries contain addresses of functions called
1160 by the generic filesystem layer to perform the complete range of
1161 filesystem related actions.
1163 The many functions in this structure are broken down into three
1164 categories: infrastructure functions (almost all of which must be
1165 implemented), operational functions (which must be implemented if a
1166 complete filesystem is provided), and efficiency functions (which need
1167 only be implemented if they can be done so efficiently, or if they have
1168 side-effects which are required by the filesystem; Tcl has less
1169 efficient emulations it can fall back on). It is important to note
1170 that, in the current version of Tcl, most of these fallbacks are only
1171 used to handle commands initiated in Tcl, not in C. What this means is,
1172 that if a \fBfile rename\fR command is issued in Tcl, and the relevant
1173 filesystem(s) do not implement their \fITcl_FSRenameFileProc\fR, Tcl's
1174 core will instead fallback on a combination of other filesystem
1175 functions (it will use \fITcl_FSCopyFileProc\fR followed by
1176 \fITcl_FSDeleteFileProc\fR, and if \fITcl_FSCopyFileProc\fR is not
1177 implemented there is a further fallback). However, if a
1178 \fITcl_FSRenameFileProc\fR command is issued at the C level, no such
1179 fallbacks occur. This is true except for the last four entries in the
1180 filesystem table (\fBlstat\fR, \fBload\fR, \fBgetcwd\fR and \fBchdir\fR)
1181 for which fallbacks do in fact occur at the C level.
1183 Any functions which take path names in Tcl_Obj form take
1184 those names in UTF\-8 form. The filesystem infrastructure API is
1185 designed to support efficient, cached conversion of these UTF\-8 paths
1186 to other native representations.
1187 .SS "EXAMPLE FILESYSTEM DEFINITION"
1189 Here is the filesystem lookup table used by the
1191 extension which allows filesystem actions to be implemented in Tcl.
1194 static Tcl_Filesystem vfsFilesystem = {
1196 sizeof(Tcl_Filesystem),
1197 TCL_FILESYSTEM_VERSION_1,
1198 &VfsPathInFilesystem,
1200 &VfsFreeInternalRep,
1201 /* No internal to normalized, since we don't create
1202 * any pure 'internal' Tcl_Obj path representations */
1204 /* No create native rep function, since we don't use
1205 * it and don't choose to support uses of
1206 * Tcl_FSNewNativePath */
1208 /* Normalize path isn't needed - we assume paths only
1209 * have one representation */
1211 &VfsFilesystemPathType,
1212 &VfsFilesystemSeparator,
1215 &VfsOpenFileChannel,
1216 &VfsMatchInDirectory,
1218 /* We choose not to support symbolic links inside our
1222 &VfsFileAttrStrings,
1225 &VfsCreateDirectory,
1226 &VfsRemoveDirectory,
1228 /* No copy file; use the core fallback mechanism */
1230 /* No rename file; use the core fallback mechanism */
1232 /* No copy directory; use the core fallback mechanism */
1234 /* Core will use stat for lstat */
1236 /* No load; use the core fallback mechanism */
1238 /* We don't need a getcwd or chdir; the core's own
1239 * internal value is suitable */
1244 .SH "FILESYSTEM INFRASTRUCTURE"
1246 These fields contain basic information about the filesystem structure
1247 and addresses of functions which are used to associate
1248 a particular filesystem with a file path, and deal with the internal
1249 handling of path representations, for example copying and freeing such
1253 The \fItypeName\fR field contains a null-terminated string that
1254 identifies the type of the filesystem implemented, e.g.
1259 .SS "STRUCTURE LENGTH"
1261 The \fIstructureLength\fR field is generally implemented as
1262 \fIsizeof(Tcl_Filesystem)\fR, and is there to allow easier
1263 binary backwards compatibility if the size of the structure
1264 changes in a future Tcl release.
1267 The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR.
1268 .SS PATHINFILESYSTEMPROC
1270 The \fIpathInFilesystemProc\fR field contains the address of a function
1271 which is called to determine whether a given path value belongs to this
1272 filesystem or not. Tcl will only call the rest of the filesystem
1273 functions with a path for which this function has returned \fBTCL_OK\fR.
1274 If the path does not belong, -1 should be returned (the behavior of Tcl
1275 for any other return value is not defined). If \fBTCL_OK\fR is returned,
1276 then the optional \fIclientDataPtr\fR output parameter can be used to
1277 return an internal (filesystem specific) representation of the path,
1278 which will be cached inside the path value, and may be retrieved
1279 efficiently by the other filesystem functions. Tcl will simultaneously
1280 cache the fact that this path belongs to this filesystem. Such caches
1281 are invalidated when filesystem structures are added or removed from
1282 Tcl's internal list of known filesystems.
1285 typedef int \fBTcl_FSPathInFilesystemProc\fR(
1286 Tcl_Obj *\fIpathPtr\fR,
1287 ClientData *\fIclientDataPtr\fR);
1289 .SS DUPINTERNALREPPROC
1291 This function makes a copy of a path's internal representation, and is
1292 called when Tcl needs to duplicate a path value. If NULL, Tcl will
1293 simply not copy the internal representation, which may then need to be
1297 typedef ClientData \fBTcl_FSDupInternalRepProc\fR(
1298 ClientData \fIclientData\fR);
1300 .SS FREEINTERNALREPPROC
1301 Free the internal representation. This must be implemented if internal
1302 representations need freeing (i.e.\ if some memory is allocated when an
1303 internal representation is generated), but may otherwise be NULL.
1306 typedef void \fBTcl_FSFreeInternalRepProc\fR(
1307 ClientData \fIclientData\fR);
1309 .SS INTERNALTONORMALIZEDPROC
1311 Function to convert internal representation to a normalized path. Only
1312 required if the filesystem creates pure path values with no string/path
1313 representation. The return value is a Tcl value whose string
1314 representation is the normalized path.
1317 typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR(
1318 ClientData \fIclientData\fR);
1320 .SS CREATEINTERNALREPPROC
1322 Function to take a path value, and calculate an internal
1323 representation for it, and store that native representation in the
1324 value. May be NULL if paths have no internal representation, or if
1325 the \fITcl_FSPathInFilesystemProc\fR for this filesystem always
1326 immediately creates an internal representation for paths it accepts.
1329 typedef ClientData \fBTcl_FSCreateInternalRepProc\fR(
1330 Tcl_Obj *\fIpathPtr\fR);
1332 .SS NORMALIZEPATHPROC
1334 Function to normalize a path. Should be implemented for all
1335 filesystems which can have multiple string representations for the same
1336 path value. In Tcl, every
1338 must have a single unique
1340 string representation. Depending on the filesystem,
1341 there may be more than one unnormalized string representation which
1342 refers to that path (e.g.\ a relative path, a path with different
1343 character case if the filesystem is case insensitive, a path contain a
1344 reference to a home directory such as
1346 a path containing symbolic
1347 links, etc). If the very last component in the path is a symbolic
1348 link, it should not be converted into the value it points to (but
1349 its case or other aspects should be made unique). All other path
1350 components should be converted from symbolic links. This one
1351 exception is required to agree with Tcl's semantics with \fBfile
1352 delete\fR, \fBfile rename\fR, \fBfile copy\fR operating on symbolic links.
1353 This function may be called with \fInextCheckpoint\fR either
1354 at the beginning of the path (i.e.\ zero), at the end of the path, or
1355 at any intermediate file separator in the path. It will never
1356 point to any other arbitrary position in the path. In the last of
1357 the three valid cases, the implementation can assume that the path
1358 up to and including the file separator is known and normalized.
1361 typedef int \fBTcl_FSNormalizePathProc\fR(
1362 Tcl_Interp *\fIinterp\fR,
1363 Tcl_Obj *\fIpathPtr\fR,
1364 int \fInextCheckpoint\fR);
1366 .SH "FILESYSTEM OPERATIONS"
1368 The fields in this section of the structure contain addresses of
1369 functions which are called to carry out the basic filesystem
1370 operations. A filesystem which expects to be used with the complete
1371 standard Tcl command set must implement all of these. If some of
1372 them are not implemented, then certain Tcl commands may fail when
1373 operating on paths within that filesystem. However, in some instances
1374 this may be desirable (for example, a read-only filesystem should not
1375 implement the last four functions, and a filesystem which does not
1376 support symbolic links need not implement the \fBreadlink\fR function,
1377 etc. The Tcl core expects filesystems to behave in this way).
1378 .SS FILESYSTEMPATHTYPEPROC
1380 Function to determine the type of a path in this filesystem. May be
1381 NULL, in which case no type information will be available to users of
1384 is used only for informational purposes,
1385 and should be returned as the string representation of the Tcl_Obj
1386 which is returned. A typical return value might be
1391 The Tcl_Obj result is owned by the filesystem and so Tcl will
1392 increment the reference count of that value if it wishes to retain a reference
1396 typedef Tcl_Obj *\fBTcl_FSFilesystemPathTypeProc\fR(
1397 Tcl_Obj *\fIpathPtr\fR);
1399 .SS FILESYSTEMSEPARATORPROC
1401 Function to return the separator character(s) for this filesystem.
1402 This need only be implemented if the filesystem wishes to use a
1403 different separator than the standard string
1406 uses, it is returned by the \fBfile separator\fR command. The
1407 return value should be a value with reference count of zero.
1410 typedef Tcl_Obj *\fBTcl_FSFilesystemSeparatorProc\fR(
1411 Tcl_Obj *\fIpathPtr\fR);
1415 Function to process a \fBTcl_FSStat\fR call. Must be implemented for any
1416 reasonable filesystem, since many Tcl level commands depend crucially
1417 upon it (e.g.\ \fBfile atime\fR, \fBfile isdirectory\fR, \fBfile size\fR,
1421 typedef int \fBTcl_FSStatProc\fR(
1422 Tcl_Obj *\fIpathPtr\fR,
1423 Tcl_StatBuf *\fIstatPtr\fR);
1426 The \fBTcl_FSStatProc\fR fills the stat structure \fIstatPtr\fR with
1427 information about the specified file. You do not need any access
1428 rights to the file to get this information but you need search rights
1429 to all directories named in the path leading to the file. The stat
1430 structure includes info regarding device, inode (always 0 on Windows),
1431 privilege mode, nlink (always 1 on Windows), user id (always 0 on
1432 Windows), group id (always 0 on Windows), rdev (same as device on
1433 Windows), size, last access time, last modification time, and
1434 last metadata change time.
1436 If the file represented by \fIpathPtr\fR exists, the
1437 \fBTcl_FSStatProc\fR returns 0 and the stat structure is filled with
1438 data. Otherwise, -1 is returned, and no stat info is given.
1441 Function to process a \fBTcl_FSAccess\fR call. Must be implemented for
1442 any reasonable filesystem, since many Tcl level commands depend crucially
1443 upon it (e.g.\ \fBfile exists\fR, \fBfile readable\fR).
1446 typedef int \fBTcl_FSAccessProc\fR(
1447 Tcl_Obj *\fIpathPtr\fR,
1451 The \fBTcl_FSAccessProc\fR checks whether the process would be allowed
1452 to read, write or test for existence of the file (or other filesystem
1453 object) whose name is in \fIpathPtr\fR. If the pathname refers to a
1454 symbolic link, then the
1455 permissions of the file referred by this symbolic link should be tested.
1457 On success (all requested permissions granted), zero is returned. On
1458 error (at least one bit in mode asked for a permission that is denied,
1459 or some other error occurred), -1 is returned.
1460 .SS OPENFILECHANNELPROC
1462 Function to process a \fBTcl_FSOpenFileChannel\fR call. Must be
1463 implemented for any reasonable filesystem, since any operations
1464 which require open or accessing a file's contents will use it
1465 (e.g.\ \fBopen\fR, \fBencoding\fR, and many Tk commands).
1468 typedef Tcl_Channel \fBTcl_FSOpenFileChannelProc\fR(
1469 Tcl_Interp *\fIinterp\fR,
1470 Tcl_Obj *\fIpathPtr\fR,
1472 int \fIpermissions\fR);
1475 The \fBTcl_FSOpenFileChannelProc\fR opens a file specified by
1476 \fIpathPtr\fR and returns a channel handle that can be used to perform
1477 input and output on the file. This API is modeled after the \fBfopen\fR
1478 procedure of the Unix standard I/O library. The syntax and meaning of
1479 all arguments is similar to those given in the Tcl \fBopen\fR command
1480 when opening a file, where the \fImode\fR argument is a combination of
1481 the POSIX flags O_RDONLY, O_WRONLY, etc. If an error occurs while
1482 opening the channel, the \fBTcl_FSOpenFileChannelProc\fR returns NULL and
1483 records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
1484 In addition, if \fIinterp\fR is non-NULL, the
1485 \fBTcl_FSOpenFileChannelProc\fR leaves an error message in \fIinterp\fR's
1486 result after any error.
1488 The newly created channel must not be registered in the supplied interpreter
1489 by a \fBTcl_FSOpenFileChannelProc\fR; that task is up to the caller of
1490 \fBTcl_FSOpenFileChannel\fR (if necessary). If one of
1491 the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
1492 previously closed, the act of creating the new channel also assigns it
1493 as a replacement for the standard channel.
1494 .SS MATCHINDIRECTORYPROC
1496 Function to process a \fBTcl_FSMatchInDirectory\fR call. If not
1497 implemented, then glob and recursive copy functionality will be lacking
1498 in the filesystem (and this may impact commands like \fBencoding names\fR
1499 which use glob functionality internally).
1502 typedef int \fBTcl_FSMatchInDirectoryProc\fR(
1503 Tcl_Interp *\fIinterp\fR,
1504 Tcl_Obj *\fIresultPtr\fR,
1505 Tcl_Obj *\fIpathPtr\fR,
1506 const char *\fIpattern\fR,
1507 Tcl_GlobTypeData *\fItypes\fR);
1510 The function should return all files or directories (or other filesystem
1511 objects) which match the given pattern and accord with the \fItypes\fR
1512 specification given. There are two ways in which this function may be
1513 called. If \fIpattern\fR is NULL, then \fIpathPtr\fR is a full path
1514 specification of a single file or directory which should be checked for
1515 existence and correct type. Otherwise, \fIpathPtr\fR is a directory, the
1516 contents of which the function should search for files or directories
1517 which have the correct type. In either case, \fIpathPtr\fR can be
1518 assumed to be both non-NULL and non-empty. It is not currently
1519 documented whether \fIpathPtr\fR will have a file separator at its end of
1520 not, so code should be flexible to both possibilities.
1522 The return value is a standard Tcl result indicating whether an error
1523 occurred in the matching process. Error messages are placed in
1524 \fIinterp\fR, unless \fIinterp\fR in NULL in which case no error
1525 message need be generated; on a \fBTCL_OK\fR result, results should be
1526 added to the \fIresultPtr\fR value given (which can be assumed to be a
1527 valid unshared Tcl list). The matches added
1528 to \fIresultPtr\fR should include any path prefix given in \fIpathPtr\fR
1529 (this usually means they will be absolute path specifications).
1530 Note that if no matches are found, that simply leads to an empty
1531 result; errors are only signaled for actual file or filesystem
1532 problems which may occur during the matching process.
1534 The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR
1535 parameter contains the following fields:
1538 typedef struct Tcl_GlobTypeData {
1539 /* Corresponds to bcdpfls as in 'find -t' */
1541 /* Corresponds to file permissions */
1543 /* Acceptable mac type */
1544 Tcl_Obj *\fImacType\fR;
1545 /* Acceptable mac creator */
1546 Tcl_Obj *\fImacCreator\fR;
1547 } \fBTcl_GlobTypeData\fR;
1550 There are two specific cases which it is important to handle correctly,
1551 both when \fItypes\fR is non-NULL. The two cases are when \fItypes->types
1552 & TCL_GLOB_TYPE_DIR\fR or \fItypes->types & TCL_GLOB_TYPE_MOUNT\fR are
1553 true (and in particular when the other flags are false). In the first of
1554 these cases, the function must list the contained directories. Tcl uses
1555 this to implement recursive globbing, so it is critical that filesystems
1556 implement directory matching correctly. In the second of these cases,
1557 with \fBTCL_GLOB_TYPE_MOUNT\fR, the filesystem must list the mount points
1558 which lie within the given \fIpathPtr\fR (and in this case, \fIpathPtr\fR
1559 need not lie within the same filesystem - different to all other cases in
1560 which this function is called). Support for this is critical if Tcl is
1561 to have seamless transitions between from one filesystem to another.
1564 Function to process a \fBTcl_FSUtime\fR call. Required to allow setting
1565 (not reading) of times with \fBfile mtime\fR, \fBfile atime\fR and the
1566 open-r/open-w/fcopy implementation of \fBfile copy\fR.
1569 typedef int \fBTcl_FSUtimeProc\fR(
1570 Tcl_Obj *\fIpathPtr\fR,
1571 struct utimbuf *\fItval\fR);
1574 The access and modification times of the file specified by \fIpathPtr\fR
1575 should be changed to the values given in the \fItval\fR structure.
1577 The return value should be 0 on success and -1 on an error, as
1578 with the system \fButime\fR.
1581 Function to process a \fBTcl_FSLink\fR call. Should be implemented
1582 only if the filesystem supports links, and may otherwise be NULL.
1585 typedef Tcl_Obj *\fBTcl_FSLinkProc\fR(
1586 Tcl_Obj *\fIlinkNamePtr\fR,
1587 Tcl_Obj *\fItoPtr\fR,
1588 int \fIlinkAction\fR);
1591 If \fItoPtr\fR is NULL, the function is being asked to read the
1592 contents of a link. The result is a Tcl_Obj specifying the contents of
1593 the link given by \fIlinkNamePtr\fR, or NULL if the link could
1594 not be read. The result is owned by the caller (and should therefore
1595 have its ref count incremented before being returned). Any callers
1596 should call \fBTcl_DecrRefCount\fR on this result when it is no longer needed.
1597 If \fItoPtr\fR is not NULL, the function should attempt to create a link.
1598 The result in this case should be \fItoPtr\fR if the link was successful
1599 and NULL otherwise. In this case the result is not owned by the caller
1600 (i.e.\ no reference count manipulations on either end are needed). See
1601 the documentation for \fBTcl_FSLink\fR for the correct interpretation
1602 of the \fIlinkAction\fR flags.
1605 Function to list any filesystem volumes added by this filesystem.
1606 Should be implemented only if the filesystem adds volumes at the head
1607 of the filesystem, so that they can be returned by \fBfile volumes\fR.
1610 typedef Tcl_Obj *\fBTcl_FSListVolumesProc\fR(void);
1613 The result should be a list of volumes added by this filesystem, or
1614 NULL (or an empty list) if no volumes are provided. The result value
1615 is considered to be owned by the filesystem (not by Tcl's core), but
1616 should be given a reference count for Tcl. Tcl will use the contents of the
1617 list and then decrement that reference count. This allows filesystems to
1618 choose whether they actually want to retain a
1621 or not (if not, they generate the list on the fly and pass it to Tcl
1622 with a reference count of 1 and then forget about the list, if yes, then
1623 they simply increment the reference count of their master list and pass it
1624 to Tcl which will copy the contents and then decrement the count back
1627 Therefore, Tcl considers return values from this proc to be read-only.
1628 .SS FILEATTRSTRINGSPROC
1630 Function to list all attribute strings which are valid for this
1631 filesystem. If not implemented the filesystem will not support
1632 the \fBfile attributes\fR command. This allows arbitrary additional
1633 information to be attached to files in the filesystem. If it is
1634 not implemented, there is no need to implement the \fBget\fR and \fBset\fR
1638 typedef const char *const *\fBTcl_FSFileAttrStringsProc\fR(
1639 Tcl_Obj *\fIpathPtr\fR,
1640 Tcl_Obj **\fIobjPtrRef\fR);
1643 The called function may either return an array of strings, or may
1644 instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR. Tcl
1645 will take that list and first increment its reference count before using it.
1646 On completion of that use, Tcl will decrement its reference count. Hence if
1647 the list should be disposed of by Tcl when done, it should have a
1648 reference count of zero, and if the list should not be disposed of, the
1649 filesystem should ensure it returns a value with a reference count
1651 .SS FILEATTRSGETPROC
1653 Function to process a \fBTcl_FSFileAttrsGet\fR call, used by \fBfile
1657 typedef int \fBTcl_FSFileAttrsGetProc\fR(
1658 Tcl_Interp *\fIinterp\fR,
1660 Tcl_Obj *\fIpathPtr\fR,
1661 Tcl_Obj **\fIobjPtrRef\fR);
1664 Returns a standard Tcl return code. The attribute value retrieved,
1665 which corresponds to the \fIindex\fR'th element in the list returned by
1666 the \fBTcl_FSFileAttrStringsProc\fR, is a Tcl_Obj placed in \fIobjPtrRef\fR (if
1667 \fBTCL_OK\fR was returned) and is likely to have a reference count of zero. Either
1668 way we must either store it somewhere (e.g.\ the Tcl result), or
1669 Incr/Decr its reference count to ensure it is properly freed.
1670 .SS FILEATTRSSETPROC
1672 Function to process a \fBTcl_FSFileAttrsSet\fR call, used by \fBfile
1673 attributes\fR. If the filesystem is read-only, there is no need
1677 typedef int \fBTcl_FSFileAttrsSetProc\fR(
1678 Tcl_Interp *\fIinterp\fR,
1680 Tcl_Obj *\fIpathPtr\fR,
1681 Tcl_Obj *\fIobjPtr\fR);
1684 The attribute value of the \fIindex\fR'th element in the list returned by
1685 the Tcl_FSFileAttrStringsProc should be set to the \fIobjPtr\fR given.
1686 .SS CREATEDIRECTORYPROC
1688 Function to process a \fBTcl_FSCreateDirectory\fR call. Should be
1689 implemented unless the FS is read-only.
1692 typedef int \fBTcl_FSCreateDirectoryProc\fR(
1693 Tcl_Obj *\fIpathPtr\fR);
1696 The return value is a standard Tcl result indicating whether an error
1697 occurred in the process. If successful, a new directory should have
1698 been added to the filesystem in the location specified by
1700 .SS REMOVEDIRECTORYPROC
1702 Function to process a \fBTcl_FSRemoveDirectory\fR call. Should be
1703 implemented unless the FS is read-only.
1706 typedef int \fBTcl_FSRemoveDirectoryProc\fR(
1707 Tcl_Obj *\fIpathPtr\fR,
1708 int \fIrecursive\fR,
1709 Tcl_Obj **\fIerrorPtr\fR);
1712 The return value is a standard Tcl result indicating whether an error
1713 occurred in the process. If successful, the directory specified by
1714 \fIpathPtr\fR should have been removed from the filesystem. If the
1715 \fIrecursive\fR flag is given, then a non-empty directory should be
1716 deleted without error. If this flag is not given, then and the
1717 directory is non-empty a POSIX
1719 error should be signaled. If an
1720 error does occur, the name of the file or directory which caused the
1721 error should be placed in \fIerrorPtr\fR.
1724 Function to process a \fBTcl_FSDeleteFile\fR call. Should be implemented
1725 unless the FS is read-only.
1728 typedef int \fBTcl_FSDeleteFileProc\fR(
1729 Tcl_Obj *\fIpathPtr\fR);
1732 The return value is a standard Tcl result indicating whether an error
1733 occurred in the process. If successful, the file specified by
1734 \fIpathPtr\fR should have been removed from the filesystem. Note that,
1735 if the filesystem supports symbolic links, Tcl will always call this
1736 function and not Tcl_FSRemoveDirectoryProc when needed to delete them
1737 (even if they are symbolic links to directories).
1738 .SH "FILESYSTEM EFFICIENCY"
1740 These functions need not be implemented for a particular filesystem
1741 because the core has a fallback implementation available. See each
1742 individual description for the consequences of leaving the field NULL.
1745 Function to process a \fBTcl_FSLstat\fR call. If not implemented, Tcl
1746 will attempt to use the \fIstatProc\fR defined above instead. Therefore
1747 it need only be implemented if a filesystem can differentiate between
1748 \fBstat\fR and \fBlstat\fR calls.
1751 typedef int \fBTcl_FSLstatProc\fR(
1752 Tcl_Obj *\fIpathPtr\fR,
1753 Tcl_StatBuf *\fIstatPtr\fR);
1756 The behavior of this function is very similar to that of the
1757 \fBTcl_FSStatProc\fR defined above, except that if it is applied
1758 to a symbolic link, it returns information about the link, not
1759 about the target file.
1762 Function to process a \fBTcl_FSCopyFile\fR call. If not implemented Tcl
1763 will fall back on \fBopen\fR-r, \fBopen\fR-w and \fBfcopy\fR as a
1765 Therefore it need only be implemented if the filesystem can perform
1766 that action more efficiently.
1769 typedef int \fBTcl_FSCopyFileProc\fR(
1770 Tcl_Obj *\fIsrcPathPtr\fR,
1771 Tcl_Obj *\fIdestPathPtr\fR);
1774 The return value is a standard Tcl result indicating whether an error
1775 occurred in the copying process. Note that, \fIdestPathPtr\fR is the
1776 name of the file which should become the copy of \fIsrcPathPtr\fR. It
1777 is never the name of a directory into which \fIsrcPathPtr\fR could be
1778 copied (i.e.\ the function is much simpler than the Tcl level \fBfile
1779 copy\fR subcommand). Note that,
1780 if the filesystem supports symbolic links, Tcl will always call this
1781 function and not \fIcopyDirectoryProc\fR when needed to copy them
1782 (even if they are symbolic links to directories). Finally, if the
1783 filesystem determines it cannot support the \fBfile copy\fR action,
1784 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
1785 result will tell Tcl to use its standard fallback mechanisms.
1788 Function to process a \fBTcl_FSRenameFile\fR call. If not implemented,
1789 Tcl will fall back on a copy and delete mechanism. Therefore it need
1790 only be implemented if the filesystem can perform that action more
1794 typedef int \fBTcl_FSRenameFileProc\fR(
1795 Tcl_Obj *\fIsrcPathPtr\fR,
1796 Tcl_Obj *\fIdestPathPtr\fR);
1799 The return value is a standard Tcl result indicating whether an error
1800 occurred in the renaming process. If the
1801 filesystem determines it cannot support the \fBfile rename\fR action,
1802 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
1803 result will tell Tcl to use its standard fallback mechanisms.
1804 .SS COPYDIRECTORYPROC
1806 Function to process a \fBTcl_FSCopyDirectory\fR call. If not
1807 implemented, Tcl will fall back on a recursive \fBfile mkdir\fR, \fBfile copy\fR
1808 mechanism. Therefore it need only be implemented if the filesystem can
1809 perform that action more efficiently.
1812 typedef int \fBTcl_FSCopyDirectoryProc\fR(
1813 Tcl_Obj *\fIsrcPathPtr\fR,
1814 Tcl_Obj *\fIdestPathPtr\fR,
1815 Tcl_Obj **\fIerrorPtr\fR);
1818 The return value is a standard Tcl result indicating whether an error
1819 occurred in the copying process. If an error does occur, the name of
1820 the file or directory which caused the error should be placed in
1821 \fIerrorPtr\fR. Note that, \fIdestPathPtr\fR is the name of the
1822 directory-name which should become the mirror-image of
1823 \fIsrcPathPtr\fR. It is not the name of a directory into which
1824 \fIsrcPathPtr\fR should be copied (i.e.\ the function is much simpler
1825 than the Tcl level \fBfile copy\fR subcommand). Finally, if the
1826 filesystem determines it cannot support the directory copy action,
1827 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
1828 result will tell Tcl to use its standard fallback mechanisms.
1831 Function to process a \fBTcl_FSLoadFile\fR call. If not implemented, Tcl
1832 will fall back on a copy to native-temp followed by a \fBTcl_FSLoadFile\fR on
1833 that temporary copy. Therefore it need only be implemented if the
1834 filesystem can load code directly, or it can be implemented simply to
1835 return \fBTCL_ERROR\fR to disable load functionality in this filesystem
1839 typedef int \fBTcl_FSLoadFileProc\fR(
1840 Tcl_Interp *\fIinterp\fR,
1841 Tcl_Obj *\fIpathPtr\fR,
1842 Tcl_LoadHandle *\fIhandlePtr\fR,
1843 Tcl_FSUnloadFileProc *\fIunloadProcPtr\fR);
1846 Returns a standard Tcl completion code. If an error occurs, an error
1847 message is left in the \fIinterp\fR's result. The function dynamically loads a
1848 binary code file into memory. On a successful load, the \fIhandlePtr\fR
1849 should be filled with a token for the dynamically loaded file, and the
1850 \fIunloadProcPtr\fR should be filled in with the address of a procedure.
1851 The unload procedure will be called with the given \fBTcl_LoadHandle\fR as its
1852 only parameter when Tcl needs to unload the file. For example, for the
1853 native filesystem, the \fBTcl_LoadHandle\fR returned is currently a token
1854 which can be used in the private \fBTclpFindSymbol\fR to access functions
1855 in the new code. Each filesystem is free to define the
1856 \fBTcl_LoadHandle\fR as it requires. Finally, if the
1857 filesystem determines it cannot support the file load action,
1858 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
1859 result will tell Tcl to use its standard fallback mechanisms.
1862 Function to unload a previously successfully loaded file. If load was
1863 implemented, then this should also be implemented, if there is any
1864 cleanup action required.
1867 typedef void \fBTcl_FSUnloadFileProc\fR(
1868 Tcl_LoadHandle \fIloadHandle\fR);
1872 Function to process a \fBTcl_FSGetCwd\fR call. Most filesystems need not
1873 implement this. It will usually only be called once, if \fBgetcwd\fR is
1874 called before \fBchdir\fR. May be NULL.
1877 typedef Tcl_Obj *\fBTcl_FSGetCwdProc\fR(
1878 Tcl_Interp *\fIinterp\fR);
1881 If the filesystem supports a native notion of a current working
1882 directory (which might perhaps change independent of Tcl), this
1883 function should return that cwd as the result, or NULL if the current
1884 directory could not be determined (e.g.\ the user does not have
1885 appropriate permissions on the cwd directory). If NULL is returned, an
1886 error message is left in the \fIinterp\fR's result.
1889 Function to process a \fBTcl_FSChdir\fR call. If filesystems do not
1890 implement this, it will be emulated by a series of directory access
1891 checks. Otherwise, virtual filesystems which do implement it need only
1892 respond with a positive return result if the \fIpathPtr\fR is a valid,
1893 accessible directory in their filesystem. They need not remember the
1894 result, since that will be automatically remembered for use by
1896 Real filesystems should carry out the correct action (i.e.\ call the
1897 correct system \fBchdir\fR API).
1900 typedef int \fBTcl_FSChdirProc\fR(
1901 Tcl_Obj *\fIpathPtr\fR);
1904 The \fBTcl_FSChdirProc\fR changes the applications current working
1905 directory to the value specified in \fIpathPtr\fR. The function returns
1906 -1 on error or 0 on success.
1908 cd(n), file(n), filename(n), load(n), open(n), pwd(n), source(n), unload(n)
1910 stat, access, filesystem, vfs, virtual filesystem
OSDN Git Service
