2 '\" Copyright (c) 2001 Vincent Darley
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 '\" RCS: @(#) $Id: FileSystem.3,v 1.32.2.2 2003/10/03 17:24:34 vincentdarley Exp $
9 '\" The definitions below are for supplemental macros used in Tcl/Tk
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
55 '\" options follow on successive lines, in four columns separated
59 '\" End of list of standard options for a Tk widget.
61 '\" .OP cmdName dbName dbClass
62 '\" Start of description of a specific option. cmdName gives the
63 '\" option's name as specified in the class command, dbName gives
64 '\" the option's name in the option database, and dbClass gives
65 '\" the option's class in the option database.
68 '\" Print arg1 underlined, then print arg2 normally.
70 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
72 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
76 '\" # Start an argument description
80 . ie !"\\$2"" .TP \\n()Cu
85 \&\\$1 \\fI\\$2\\fP (\\$3)
98 '\" # define tabbing values for .AP
101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
107 .AS Tcl_Interp Tcl_CreateInterp in/out
108 '\" # BS - start boxed text
109 '\" # ^y = starting y location
117 .if n \l'\\n(.lu\(ul'
120 '\" # BE - end boxed text (draw box now)
125 .ie n \l'\\n(^lu\(ul'
127 .\" Draw four-sided box normally, but don't draw top of
128 .\" box if the box started on an earlier page.
130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 '\" # VS - start vertical sidebar
141 '\" # ^Y = starting y location
142 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
146 .ie n 'mc \s12\(br\s0
149 '\" # VE - end of vertical sidebar
157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
164 '\" # Special macro to handle page bottom: finish off current
165 '\" # box/sidebar if in box/sidebar mode, then invoked standard
166 '\" # page bottom macro.
173 .\" Draw three-sided box if this is the box's first page,
174 .\" draw two sides but no top otherwise.
175 .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
176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
179 .nr ^x \\n(^tu+1v-\\n(^Yu
180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
193 '\" # DS - begin display
199 '\" # DE - end display
205 '\" # SO - start of list of standard options
207 .SH "STANDARD OPTIONS"
213 '\" # SE - end of list of standard options
218 See the \\fBoptions\\fR manual entry for details on the standard options.
220 '\" # OP - start of full description for a single option
225 Command-Line Name: \\fB\\$1\\fR
226 Database Name: \\fB\\$2\\fR
227 Database Class: \\fB\\$3\\fR
231 '\" # CS - begin code excerpt
237 '\" # CE - end code excerpt
245 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
248 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_FSLoadFile, 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_AllocStatBuf \- procedures to interact with any filesystem
251 \fB#include <tcl.h>\fR
254 \fBTcl_FSRegister\fR(\fIclientData, fsPtr\fR)
257 \fBTcl_FSUnregister\fR(\fIfsPtr\fR)
260 \fBTcl_FSData\fR(\fIfsPtr\fR)
263 \fBTcl_FSMountsChanged\fR(\fIfsPtr\fR)
266 \fBTcl_FSGetFileSystemForPath\fR(\fIpathObjPtr\fR)
269 \fBTcl_FSGetPathType\fR(\fIpathObjPtr\fR)
272 \fBTcl_FSCopyFile\fR(\fIsrcPathPtr, destPathPtr\fR)
275 \fBTcl_FSCopyDirectory\fR(\fIsrcPathPtr, destPathPtr, errorPtr\fR)
278 \fBTcl_FSCreateDirectory\fR(\fIpathPtr\fR)
281 \fBTcl_FSDeleteFile\fR(\fIpathPtr\fR)
284 \fBTcl_FSRemoveDirectory\fR(\fIpathPtr, int recursive, errorPtr\fR)
287 \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR)
290 \fBTcl_FSListVolumes\fR(\fIvoid\fR)
293 \fBTcl_FSEvalFile\fR(\fIinterp, pathPtr\fR)
296 \fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr, handlePtr, unloadProcPtr\fR)
299 \fBTcl_FSMatchInDirectory\fR(\fIinterp, result, pathPtr, pattern, types\fR)
302 \fBTcl_FSLink\fR(\fIlinkNamePtr, toPtr, linkAction\fR)
305 \fBTcl_FSLstat\fR(\fIpathPtr, statPtr\fR)
308 \fBTcl_FSUtime\fR(\fIpathPtr, tval\fR)
311 \fBTcl_FSFileAttrsGet\fR(\fIinterp, int index, pathPtr, objPtrRef\fR)
314 \fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR)
317 \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR)
320 \fBTcl_FSStat\fR(\fIpathPtr, statPtr\fR)
323 \fBTcl_FSAccess\fR(\fIpathPtr, mode\fR)
326 \fBTcl_FSOpenFileChannel\fR(\fIinterp, pathPtr, modeString, permissions\fR)
329 \fBTcl_FSGetCwd\fR(\fIinterp\fR)
332 \fBTcl_FSChdir\fR(\fIpathPtr\fR)
335 \fBTcl_FSPathSeparator\fR(\fIpathPtr\fR)
338 \fBTcl_FSJoinPath\fR(\fIlistObj, elements\fR)
341 \fBTcl_FSSplitPath\fR(\fIpathPtr, lenPtr\fR)
344 \fBTcl_FSEqualPaths\fR(\fIfirstPtr, secondPtr\fR)
347 \fBTcl_FSGetNormalizedPath\fR(\fIinterp, pathPtr\fR)
350 \fBTcl_FSJoinToPath\fR(\fIbasePtr, objc, objv\fR)
353 \fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR)
356 \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR)
359 \fBTcl_FSGetTranslatedPath\fR(\fIinterp, pathPtr\fR)
362 \fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR)
365 \fBTcl_FSNewNativePath\fR(\fIfsPtr, clientData\fR)
368 \fBTcl_FSGetNativePath\fR(\fIpathPtr\fR)
371 \fBTcl_FSFileSystemInfo\fR(\fIpathPtr\fR)
374 \fBTcl_AllocStatBuf\fR()
376 .AS Tcl_Filesystem *fsPtr in
377 .AP Tcl_Filesystem *fsPtr in
378 Points to a structure containing the addresses of procedures that
379 can be called to perform the various filesystem operations.
380 .AP Tcl_Obj *pathPtr in
381 The path represented by this object is used for the operation in
382 question. If the object does not already have an internal \fBpath\fR
383 representation, it will be converted to have one.
384 .AP Tcl_Obj *srcPathPtr in
385 As for \fBpathPtr\fR, but used for the source file for a copy or
387 .AP Tcl_Obj *destPathPtr in
388 As for \fBpathPtr\fR, but used for the destination filename for a copy or
390 .AP "CONST char" *pattern in
391 Only files or directories matching this pattern will be returned by
392 \fBTcl_FSMatchInDirectory\fR.
393 .AP GlobTypeData *types in
394 Only files or directories matching the type descriptions contained in
395 this structure will be returned by \fBTcl_FSMatchInDirectory\fR. It
396 is very important that the 'directory' flag is properly handled.
397 This parameter may be NULL.
398 .AP Tcl_Interp *interp in
399 Interpreter to use either for results, evaluation, or reporting error
401 .AP ClientData clientData in
402 The native description of the path object to create.
403 .AP Tcl_Obj *firstPtr in
404 The first of two path objects to compare. The object may be converted
406 .AP Tcl_Obj *secondPtr in
407 The second of two path objects to compare. The object may be converted
409 .AP Tcl_Obj *listObj in
410 The list of path elements to operate on with a \fBjoin\fR operation.
412 If non-negative, the number of elements in the listObj which should
413 be joined together. If negative, then all elements are joined.
414 .AP Tcl_Obj **errorPtr out
415 In the case of an error, filled with an object containing the name of
416 the file which caused an error in the various copy/rename operations.
417 .AP Tcl_Obj **objPtrRef out
418 Filled with an object containing the result of the operation.
419 .AP Tcl_Obj *result out
420 Pre-allocated object in which to store (by lappending) the list of
421 files or directories which are successfully matched in
422 \fBTcl_FSMatchInDirectory\fR.
424 Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. R_OK,
425 W_OK and X_OK request checking whether the file exists and has read,
426 write and execute permissions, respectively. F_OK just requests
427 checking for the existence of the file.
428 .AP Tcl_StatBuf *statPtr out
429 The structure that contains the result of a stat or lstat operation.
430 .AP "CONST char" *sym1 in
431 Name of a procedure to look up in the file's symbol table
432 .AP "CONST char" *sym2 in
433 Name of a procedure to look up in the file's symbol table
434 .AP Tcl_PackageInitProc **proc1Ptr out
435 Filled with the init function for this code.
436 .AP Tcl_PackageInitProc **proc2Ptr out
437 Filled with the safe-init function for this code.
438 .AP ClientData *clientDataPtr out
439 Filled with the clientData value to pass to this code's unload
440 function when it is called.
441 .AP TclfsUnloadFileProc_ **unloadProcPtr out
442 Filled with the function to use to unload this piece of code.
444 The access and modification times in this structure are read and
445 used to set those values for a given file.
446 .AP "CONST char" *modeString in
447 Specifies how the file is to be accessed. May have any of the values
448 allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
449 .AP int permissions in
450 POSIX-style permission flags such as 0644. If a new file is created, these
451 permissions will be set on the created file.
453 If non-NULL, filled with the number of elements in the split path.
454 .AP Tcl_Obj *basePtr in
455 The base path on to which to join the given elements. May be NULL.
457 The number of elements in \fIobjv\fR.
458 .AP "Tcl_Obj *CONST" objv[] in
459 The elements to join to the given base path.
464 There are several reasons for calling the \fBTcl_FS...\fR functions
465 rather than calling system level functions like \fBaccess\fR and
466 \fBstat\fR directly. First, they will work cross-platform, so an
467 extension which calls them should work unmodified on Unix, MacOS and
468 Windows. Second, the Windows implementation of some of these functions
469 fixes some bugs in the system level calls. Third, these function calls
470 deal with any 'Utf to platform-native' path conversions which may be
471 required (and may cache the results of such conversions for greater
472 efficiency on subsequent calls). Fourth, and perhaps most importantly,
473 all of these functions are 'virtual filesystem aware'. Any virtual
474 filesystem which has been registered (through
475 \fBTcl_FSRegister\fR) may reroute file access to alternative
476 media or access methods. This means that all of these functions (and
477 therefore the corresponding \fBfile\fR, \fBglob\fR, \fBpwd\fR, \fBcd\fR,
478 \fBopen\fR, etc. Tcl commands) may be operate on 'files' which are not
479 native files in the native filesystem. This also means that any Tcl
480 extension which accesses the filesystem through this API is
481 automatically 'virtual filesystem aware'. Of course, if an extension
482 accesses the native filesystem directly (through platform-specific
483 APIs, for example), then Tcl cannot intercept such calls.
485 If appropriate vfs's have been registered, the 'files' may, to give two
486 examples, be remote (e.g. situated on a remote ftp server) or archived
487 (e.g. lying inside a .zip archive). Such registered filesystems provide
488 a lookup table of functions to implement all or some of the functionality
489 listed here. Finally, the \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR calls
490 abstract away from what the 'struct stat' buffer buffer is actually
491 declared to be, allowing the same code to be used both on systems with
492 and systems without support for files larger than 2GB in size.
494 The \fBTcl_FS...\fR are objectified and may cache internal
495 representations and other path-related strings (e.g. the current working
496 directory). One side-effect of this is that one must not pass in objects
497 with a refCount of zero to any of these functions. If such calls were
498 handled, they might result
499 in memory leaks (under some circumstances, the filesystem code may wish
500 to retain a reference to the passed in object, and so one must not assume
501 that after any of these calls return, the object still has a refCount of
502 zero - it may have been incremented), or in a direct segfault
503 due to the object being freed part way through the complex object
504 manipulation required to ensure that the path is fully normalized and
505 absolute for filesystem determination. The practical lesson to learn
506 from this is that \fBTcl_Obj *path = Tcl_NewStringObj(...) ;
507 Tcl_FS...(path) ; Tcl_DecrRefCount(path)\fR is wrong, and may segfault.
508 The 'path' must have its refCount incremented before passing it in, or
509 decrementing it. For this reason, objects with a refCount of zero are
510 considered not to be valid filesystem paths and calling any Tcl_FS API
511 with such an object will result in no action being taken.
513 \fBTcl_FSCopyFile\fR attempts to copy the file given by srcPathPtr to the
514 path name given by destPathPtr. If the two paths given lie in the same
515 filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
516 filesystem's 'copy file' function is called (if it is non-NULL).
517 Otherwise the function returns -1 and sets Tcl's errno to the 'EXDEV'
518 posix error code (which signifies a 'cross-domain link').
520 \fBTcl_FSCopyDirectory\fR attempts to copy the directory given by srcPathPtr to the
521 path name given by destPathPtr. If the two paths given lie in the same
522 filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
523 filesystem's 'copy file' function is called (if it is non-NULL).
524 Otherwise the function returns -1 and sets Tcl's errno to the 'EXDEV'
525 posix error code (which signifies a 'cross-domain link').
527 \fBTcl_FSCreateDirectory\fR attempts to create the directory given by
528 pathPtr by calling the owning filesystem's 'create directory'
531 \fBTcl_FSDeleteFile\fR attempts to delete the file given by
532 pathPtr by calling the owning filesystem's 'delete file'
535 \fBTcl_FSRemoveDirectory\fR attempts to remove the directory given by
536 pathPtr by calling the owning filesystem's 'remove directory'
539 \fBTcl_FSRenameFile\fR attempts to rename the file or directory given by
540 srcPathPtr to the path name given by destPathPtr. If the two paths
541 given lie in the same filesystem (according to
542 \fBTcl_FSGetFileSystemForPath\fR) then that filesystem's 'rename file'
543 function is called (if it is non-NULL). Otherwise the function returns -1
544 and sets Tcl's errno to the 'EXDEV' posix error code (which signifies
545 a ``cross-domain link'').
547 \fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL 'list
548 volumes' function and asks them to return their list of root volumes. It
549 accumulates the return values in a list which is returned to the
550 caller (with a refCount of 0).
552 \fBTcl_FSEvalFile\fR reads the file given by \fIpathPtr\fR and evaluates
553 its contents as a Tcl script. It returns the same information as
555 If the file couldn't be read then a Tcl error is returned to describe
556 why the file couldn't be read.
557 The eofchar for files is '\\32' (^Z) for all platforms.
558 If you require a ``^Z'' in code for string comparison, you can use
559 ``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
560 interpreter into ``^Z''.
562 \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
563 returns the addresses of two procedures within that file, if they are
564 defined. The appropriate function for the filesystem to which pathPtr
565 belongs will be called. If that filesystem does not implement this
566 function (most virtual filesystems will not, because of OS limitations
567 in dynamically loading binary code), Tcl will attempt to copy the file
568 to a temporary directory and load that temporary file.
570 Returns a standard Tcl completion code. If an error occurs, an error
571 message is left in the interp's result.
573 \fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a
574 directory for all files which match a given pattern. The appropriate
575 function for the filesystem to which pathPtr belongs will be called.
577 The return value is a standard Tcl result indicating whether an error
578 occurred in globbing. Error messages are placed in interp, but good
579 results are placed in the resultPtr given.
581 Note that the 'glob' code implements recursive patterns internally, so
582 this function will only ever be passed simple patterns, which can be
583 matched using the logic of 'string match'. To handle recursion, Tcl
584 will call this function frequently asking only for directories to be
587 \fBTcl_FSLink\fR replaces the library version of readlink(), and
588 extends it to support the creation of links. The appropriate function
589 for the filesystem to which linkNamePtr belongs will be called.
591 If the \fItoPtr\fR is NULL, a readlink action is performed. The result
592 is a Tcl_Obj specifying the contents of the symbolic link given by
593 \fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned
594 by the caller, which should call Tcl_DecrRefCount when the result is no
595 longer needed. If the \fItoPtr\fR is not NULL, Tcl should create a link
596 of one of the types passed in in the \fIlinkAction\fR flag. This flag is
597 an or'd combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CREATE_HARD_LINK.
598 Where a choice exists (i.e. more than one flag is passed in), the Tcl
599 convention is to prefer symbolic links. When a link is successfully
600 created, the return value should be \fItoPtr\fR (which is therefore
601 already owned by the caller). If unsuccessful, NULL should be
604 \fBTcl_FSLstat\fR fills the stat structure \fIstatPtr\fR with information
605 about the specified file. You do not need any access rights to the
606 file to get this information but you need search rights to all
607 directories named in the path leading to the file. The stat structure
608 includes info regarding device, inode (always 0 on Windows),
609 privilege mode, nlink (always 1 on Windows), user id (always 0 on
610 Windows), group id (always 0 on Windows), rdev (same as device on
611 Windows), size, last access time, last modification time, and creation
614 If \fIpath\fR exists, \fBTcl_FSLstat\fR returns 0 and the stat structure
615 is filled with data. Otherwise, -1 is returned, and no stat info is
618 \fBTcl_FSUtime\fR replaces the library version of utime.
620 For results see 'utime' documentation. If successful, the function
621 will update the 'atime' and 'mtime' values of the file given.
623 \fBTcl_FSFileAttrsGet\fR implements read access for the hookable 'file
624 attributes' subcommand. The appropriate function for the filesystem to
625 which pathPtr belongs will be called.
627 If the result is TCL_OK, then an object was placed in objPtrRef, which
628 will only be temporarily valid (unless Tcl_IncrRefCount is called).
630 \fBTcl_FSFileAttrsSet\fR implements write access for the hookable 'file
631 attributes' subcommand. The appropriate function for the filesystem to
632 which pathPtr belongs will be called.
634 \fBTcl_FSFileAttrStrings\fR implements part of the hookable 'file attributes'
635 subcommand. The appropriate function for the filesystem to which
636 pathPtr belongs will be called.
638 The called procedure may either return an array of strings, or may
639 instead return NULL and place a Tcl list into the given objPtrRef. Tcl
640 will take that list and first increment its refCount before using it.
641 On completion of that use, Tcl will decrement its refCount. Hence if
642 the list should be disposed of by Tcl when done, it should have a
643 refCount of zero, and if the list should not be disposed of, the
644 filesystem should ensure it retains a refCount on the object.
646 \fBTcl_FSAccess\fR checks whether the process would be allowed to read,
647 write or test for existence of the file (or other file system object)
648 whose name is pathname. If pathname is a symbolic link on Unix,
649 then permissions of the file referred by this symbolic link are
652 On success (all requested permissions granted), zero is returned. On
653 error (at least one bit in mode asked for a permission that is denied,
654 or some other error occurred), -1 is returned.
656 \fBTcl_FSStat\fR fills the stat structure \fIstatPtr\fR with information
657 about the specified file. You do not need any access rights to the
658 file to get this information but you need search rights to all
659 directories named in the path leading to the file. The stat structure
660 includes info regarding device, inode (always 0 on Windows),
661 privilege mode, nlink (always 1 on Windows), user id (always 0 on
662 Windows), group id (always 0 on Windows), rdev (same as device on
663 Windows), size, last access time, last modification time, and creation
666 If \fIpath\fR exists, \fBTcl_FSStat\fR returns 0 and the stat structure
667 is filled with data. Otherwise, -1 is returned, and no stat info is
670 \fBTcl_FSOpenFileChannel\fR opens a file specified by \fIpathPtr\fR and
671 returns a channel handle that can be used to perform input and output on
672 the file. This API is modeled after the \fBfopen\fR procedure of
673 the Unix standard I/O library.
674 The syntax and meaning of all arguments is similar to those
675 given in the Tcl \fBopen\fR command when opening a file.
676 If an error occurs while opening the channel, \fBTcl_FSOpenFileChannel\fR
677 returns NULL and records a POSIX error code that can be
678 retrieved with \fBTcl_GetErrno\fR.
679 In addition, if \fIinterp\fR is non-NULL, \fBTcl_FSOpenFileChannel\fR
680 leaves an error message in \fIinterp\fR's result after any error.
682 The newly created channel is not registered in the supplied interpreter; to
683 register it, use \fBTcl_RegisterChannel\fR, described below.
684 If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
685 previously closed, the act of creating the new channel also assigns it as a
686 replacement for the standard channel.
688 \fBTcl_FSGetCwd\fR replaces the library version of getcwd().
690 It returns the Tcl library's current working directory. This may be
691 different to the native platform's working directory, in the case for
692 which the cwd is not in the native filesystem.
694 The result is a pointer to a Tcl_Obj specifying the current directory,
695 or NULL if the current directory could not be determined. If NULL is
696 returned, an error message is left in the interp's result.
698 The result already has its refCount incremented for the caller. When
699 it is no longer needed, that refCount should be decremented. This is
700 needed for thread-safety purposes, to allow multiple threads to access
701 this and related functions, while ensuring the results are always
704 \fBTcl_FSChdir\fR replaces the library version of chdir(). The path is
705 normalized and then passed to the filesystem which claims it. If that
706 filesystem does not implement this function, Tcl will fallback to a
707 combination of stat and access to check whether the directory exists
708 and has appropriate permissions.
710 For results, see chdir() documentation. If successful, we keep a
711 record of the successful path in cwdPathPtr for subsequent calls to
714 \fBTcl_FSPathSeparator\fR returns the separator character to be used for
715 most specific element of the path specified by pathPtr (i.e. the last
718 The separator is returned as a Tcl_Obj containing a string of length
719 1. If the path is invalid, NULL is returned.
721 \fBTcl_FSJoinPath\fR takes the given Tcl_Obj, which should be a valid list,
722 and returns the path object given by considering the first 'elements'
723 elements as valid path segments. If elements < 0, we use the entire
726 Returns object with refCount of zero, containing the joined path.
728 \fBTcl_FSSplitPath\fR takes the given Tcl_Obj, which should be a valid path,
729 and returns a Tcl List object containing each segment of that path as
732 Returns list object with refCount of zero. If the passed in lenPtr is
733 non-NULL, we use it to return the number of elements in the returned
736 \fBTcl_FSEqualPaths\fR tests whether the two paths given represent the same
739 It returns 1 if the paths are equal, and 0 if they are different. If
740 either path is NULL, 0 is always returned.
742 \fBTcl_FSGetNormalizedPath\fR this important function attempts to extract
743 from the given Tcl_Obj a unique normalized path representation, whose
744 string value can be used as a unique identifier for the file.
746 It returns the normalized path object, with refCount of zero, or NULL
747 if the path was invalid or could otherwise not be successfully
748 converted. Extraction of absolute, normalized paths is very
749 efficient (because the filesystem operates on these representations
750 internally), although the result when the filesystem contains
751 numerous symbolic links may not be the most user-friendly
754 \fBTcl_FSJoinToPath\fR takes the given object, which should usually be a
755 valid path or NULL, and joins onto it the array of paths segments
758 Returns object with refCount of zero, containing the joined path.
760 \fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid
761 Tcl path type, taking account of the fact that the cwd may have changed
762 even if this object is already supposedly of the correct type.
763 The filename may begin with "~" (to indicate current user's home
764 directory) or "~<user>" (to indicate any user's home directory).
766 If the conversion succeeds (i.e. the object is a valid path in one of
767 the current filesystems), then TCL_OK is returned. Otherwise
768 TCL_ERROR is returned, and an error message may
769 be left in the interpreter.
771 \fBTcl_FSGetInternalRep\fR extracts the internal representation of a given
772 path object, in the given filesystem. If the path object belongs to a
773 different filesystem, we return NULL. If the internal representation is
774 currently NULL, we attempt to generate it, by calling the filesystem's
775 \fBTcl_FSCreateInternalRepProc\fR.
777 Returns NULL or a valid internal path representation. This internal
778 representation is cached, so that repeated calls to this function will
779 not require additional conversions.
781 \fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path
782 from the given Tcl_Obj.
784 If the translation succeeds (i.e. the object is a valid path), then it is
785 returned. Otherwise NULL will be returned, and an error message may be
786 left in the interpreter. A "translated" path is one which contains no
787 "~" or "~user" sequences (these have been expanded to their current
788 representation in the filesystem). The object returned is owned by the
789 caller, which must store it or call Tcl_DecrRefCount to ensure memory is
790 freed. This function is of little practical use, and
791 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually
792 better functions to use for most purposes.
794 \fBTcl_FSGetTranslatedStringPath\fR does the same as
795 \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
796 The string returned is dynamically allocated and owned by the caller,
797 which must store it or call ckfree to ensure it is freed. Again,
798 \fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually
799 better functions to use for most purposes.
801 \fBTcl_FSNewNativePath\fR performs something like that reverse of the
802 usual obj->path->nativerep conversions. If some code retrieves a path
803 in native form (from, e.g. readlink or a native dialog), and that path
804 is to be used at the Tcl level, then calling this function is an
805 efficient way of creating the appropriate path object type.
807 The resulting object is a pure 'path' object, which will only receive
808 a Utf-8 string representation if that is required by some Tcl code.
810 \fBTcl_FSGetNativePath\fR is for use by the Win/Unix/MacOS native
811 filesystems, so that they can easily retrieve the native (char* or
812 TCHAR*) representation of a path. This function is a convenience
813 wrapper around \fBTcl_FSGetInternalRep\fR, and assumes the native
814 representation is string-based. It may be desirable in the future
815 to have non-string-based native representations (for example, on
816 MacOS, a representation using a fileSpec of FSRef structure would
817 probably be more efficient). On Windows a full Unicode
818 representation would allow for paths of unlimited length. Currently
819 the representation is simply a character string containing the
820 complete, absolute path in the native encoding.
822 The native representation is cached so that repeated calls to this
823 function will not require additional conversions.
825 \fBTcl_FSFileSystemInfo\fR returns a list of two elements. The first
826 element is the name of the filesystem (e.g. "native" or "vfs" or "zip"
827 or "prowrap", perhaps), and the second is the particular type of the
828 given path within that filesystem (which is filesystem dependent). The
829 second element may be empty if the filesystem does not provide a
830 further categorization of files.
832 A valid list object is returned, unless the path object is not
833 recognized, when NULL will be returned.
835 \fBTcl_FSGetFileSystemForPath\fR returns the a pointer to the
836 \fBTcl_Filesystem\fR which accepts this path as valid.
838 If no filesystem will accept the path, NULL is returned.
840 \fBTcl_FSGetPathType\fR determines whether the given path is relative
841 to the current directory, relative to the current volume, or
844 It returns one of TCL_PATH_ABSOLUTE, TCL_PATH_RELATIVE, or
845 TCL_PATH_VOLUME_RELATIVE
847 \fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system
848 heap (which may be deallocated by being passed to \fBckfree\fR.) This
849 allows extensions to invoke \fBTcl_FSStat\fR and \fBTcl_FSLStat\fR
850 without being dependent on the size of the buffer. That in turn
851 depends on the flags used to build Tcl.
855 A filesystem provides a \fBTcl_Filesystem\fR structure that contains
856 pointers to functions that implement the various operations on a
857 filesystem; these operations are invoked as needed by the generic
858 layer, which generally occurs through the functions listed above.
860 The \fBTcl_Filesystem\fR structures are manipulated using the following
863 \fBTcl_FSRegister\fR takes a pointer to a filesystem structure and an
864 optional piece of data to associated with that filesystem. On calling
865 this function, Tcl will attach the filesystem to the list of known
866 filesystems, and it will become fully functional immediately. Tcl does
867 not check if the same filesystem is registered multiple times (and in
868 general that is not a good thing to do). TCL_OK will be returned.
870 \fBTcl_FSUnregister\fR removes the given filesystem structure from
871 the list of known filesystems, if it is known, and returns TCL_OK. If
872 the filesystem is not currently registered, TCL_ERROR is returned.
874 \fBTcl_FSData\fR will return the ClientData associated with the given
875 filesystem, if that filesystem is registered. Otherwise it will
878 \fBTcl_FSMountsChanged\fR is used to inform the Tcl's core that
879 the set of mount points for the given (already registered) filesystem
880 have changed, and that cached file representations may therefore no
883 The \fBTcl_Filesystem\fR structure contains the following fields:
885 typedef struct Tcl_Filesystem {
886 CONST char *\fItypeName\fR;
887 int \fIstructureLength\fR;
888 Tcl_FSVersion \fIversion\fR;
889 Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR;
890 Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR;
891 Tcl_FSFreeInternalRepProc *\fIfreeInternalRepProc\fR;
892 Tcl_FSInternalToNormalizedProc *\fIinternalToNormalizedProc\fR;
893 Tcl_FSCreateInternalRepProc *\fIcreateInternalRepProc\fR;
894 Tcl_FSNormalizePathProc *\fInormalizePathProc\fR;
895 Tcl_FSFilesystemPathTypeProc *\fIfilesystemPathTypeProc\fR;
896 Tcl_FSFilesystemSeparatorProc *\fIfilesystemSeparatorProc\fR;
897 Tcl_FSStatProc *\fIstatProc\fR;
898 Tcl_FSAccessProc *\fIaccessProc\fR;
899 Tcl_FSOpenFileChannelProc *\fIopenFileChannelProc\fR;
900 Tcl_FSMatchInDirectoryProc *\fImatchInDirectoryProc\fR;
901 Tcl_FSUtimeProc *\fIutimeProc\fR;
902 Tcl_FSLinkProc *\fIlinkProc\fR;
903 Tcl_FSListVolumesProc *\fIlistVolumesProc\fR;
904 Tcl_FSFileAttrStringsProc *\fIfileAttrStringsProc\fR;
905 Tcl_FSFileAttrsGetProc *\fIfileAttrsGetProc\fR;
906 Tcl_FSFileAttrsSetProc *\fIfileAttrsSetProc\fR;
907 Tcl_FSCreateDirectoryProc *\fIcreateDirectoryProc\fR;
908 Tcl_FSRemoveDirectoryProc *\fIremoveDirectoryProc\fR;
909 Tcl_FSDeleteFileProc *\fIdeleteFileProc\fR;
910 Tcl_FSCopyFileProc *\fIcopyFileProc\fR;
911 Tcl_FSRenameFileProc *\fIrenameFileProc\fR;
912 Tcl_FSCopyDirectoryProc *\fIcopyDirectoryProc\fR;
913 Tcl_FSLstatProc *\fIlstatProc\fR;
914 Tcl_FSLoadFileProc *\fIloadFileProc\fR;
915 Tcl_FSGetCwdProc *\fIgetCwdProc\fR;
916 Tcl_FSChdirProc *\fIchdirProc\fR;
920 Except for the first three fields in this structure which contain
921 simple data elements, all entries contain addresses of functions called
922 by the generic filesystem layer to perform the complete range of
923 filesystem related actions.
925 The many functions in this structure are broken down into three
926 categories: infrastructure functions (almost all of which must be
927 implemented), operational functions (which must be implemented if a
928 complete filesystem is provided), and efficiency functions (which need
929 only be implemented if they can be done so efficiently, or if they have
930 side-effects which are required by the filesystem; Tcl has less
931 efficient emulations it can fall back on). It is important to note
932 that, in the current version of Tcl, most of these fallbacks are only
933 used to handle commands initiated in Tcl, not in C. What this means is,
934 that if a 'file rename' command is issued in Tcl, and the relevant
935 filesystem(s) do not implement their \fITcl_FSRenameFileProc\fR, Tcl's
936 core will instead fallback on a combination of other filesystem
937 functions (it will use \fITcl_FSCopyFileProc\fR followed by
938 \fITcl_FSDeleteFileProc\fR, and if \fITcl_FSCopyFileProc\fR is not
939 implemented there is a further fallback). However, if a
940 \fITcl_FSRenameFile\fR command is issued at the C level, no such
941 fallbacks occur. This is true except for the last four entries in the
942 filesystem table (lstat, load, getcwd and chdir)
943 for which fallbacks do in fact occur at the C level.
945 As an example, here is the filesystem lookup table used by the
946 "vfs" extension which allows filesystem actions to be implemented
949 static Tcl_Filesystem vfsFilesystem = {
951 sizeof(Tcl_Filesystem),
952 TCL_FILESYSTEM_VERSION_1,
953 &VfsPathInFilesystem,
956 /* No internal to normalized, since we don't create any
957 * pure 'internal' Tcl_Obj path representations */
959 /* No create native rep function, since we don't use it
960 * and don't choose to support uses of 'Tcl_FSNewNativePath' */
962 /* Normalize path isn't needed - we assume paths only have
963 * one representation */
965 &VfsFilesystemPathType,
966 &VfsFilesystemSeparator,
970 &VfsMatchInDirectory,
972 /* We choose not to support symbolic links inside our vfs's */
981 /* No copy file - fallback will occur at Tcl level */
983 /* No rename file - fallback will occur at Tcl level */
985 /* No copy directory - fallback will occur at Tcl level */
987 /* Core will use stat for lstat */
989 /* No load - fallback on core implementation */
991 /* We don't need a getcwd or chdir - fallback on Tcl's versions */
997 Any functions which take path names in Tcl_Obj form take
998 those names in UTF\-8 form. The filesystem infrastructure API is
999 designed to support efficient, cached conversion of these UTF\-8 paths
1000 to other native representations.
1003 The \fItypeName\fR field contains a null-terminated string that
1004 identifies the type of the filesystem implemented, e.g.
1005 \fBnative\fR or \fBzip\fR or \fBvfs\fR.
1007 .SH "STRUCTURE LENGTH"
1009 The \fIstructureLength\fR field is generally implemented as
1010 \fIsizeof(Tcl_Filesystem)\fR, and is there to allow easier
1011 binary backwards compatibility if the size of the structure
1012 changes in a future Tcl release.
1015 The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR.
1016 .SH "FILESYSTEM INFRASTRUCTURE"
1018 These fields contain addresses of functions which are used to associate
1019 a particular filesystem with a file path, and deal with the internal
1020 handling of path representations, for example copying and freeing such
1022 .SH PATHINFILESYSTEMPROC
1024 The \fIpathInFilesystemProc\fR field contains the address of a function
1025 which is called to determine whether a given path object belongs to this
1026 filesystem or not. Tcl will only call the rest of the filesystem
1027 functions with a path for which this function has returned \fBTCL_OK\fR.
1028 If the path does not belong, -1 should be returned (the behaviour of Tcl
1029 for any other return value is not defined). If \fBTCL_OK\fR is returned,
1030 then the optional \fBclientDataPtr\fR output parameter can be used to
1031 return an internal (filesystem specific) representation of the path,
1032 which will be cached inside the path object, and may be retrieved
1033 efficiently by the other filesystem functions. Tcl will simultaneously
1034 cache the fact that this path belongs to this filesystem. Such caches
1035 are invalidated when filesystem structures are added or removed from
1036 Tcl's internal list of known filesystems.
1039 typedef int Tcl_FSPathInFilesystemProc(
1040 Tcl_Obj *\fIpathPtr\fR,
1041 ClientData *\fIclientDataPtr\fR);
1043 .SH DUPINTERNALREPPROC
1045 This function makes a copy of a path's internal representation, and is
1046 called when Tcl needs to duplicate a path object. If NULL, Tcl will
1047 simply not copy the internal representation, which may then need to be
1051 typedef ClientData Tcl_FSDupInternalRepProc(
1052 ClientData \fIclientData\fR);
1054 .SH FREEINTERNALREPPROC
1055 Free the internal representation. This must be implemented if internal
1056 representations need freeing (i.e. if some memory is allocated when an
1057 internal representation is generated), but may otherwise be NULL.
1060 typedef void Tcl_FSFreeInternalRepProc(
1061 ClientData \fIclientData\fR);
1063 .SH INTERNALTONORMALIZEDPROC
1065 Function to convert internal representation to a normalized path. Only
1066 required if the filesystem creates pure path objects with no string/path
1067 representation. The return value is a Tcl object whose string
1068 representation is the normalized path.
1071 typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
1072 ClientData \fIclientData\fR);
1074 .SH CREATEINTERNALREPPROC
1076 Function to take a path object, and calculate an internal
1077 representation for it, and store that native representation in the
1078 object. May be NULL if paths have no internal representation, or if
1079 the \fITcl_FSPathInFilesystemProc\fR for this filesystem always
1080 immediately creates an internal representation for paths it accepts.
1083 typedef ClientData Tcl_FSCreateInternalRepProc(
1084 Tcl_Obj *\fIpathPtr\fR);
1086 .SH NORMALIZEPATHPROC
1088 Function to normalize a path. Should be implemented for all
1089 filesystems which can have multiple string representations for the same
1090 path object. In Tcl, every 'path' must have a single unique 'normalized'
1091 string representation. Depending on the filesystem,
1092 there may be more than one unnormalized string representation which
1093 refers to that path (e.g. a relative path, a path with different
1094 character case if the filesystem is case insensitive, a path contain a
1095 reference to a home directory such as '~', a path containing symbolic
1096 links, etc). If the very last component in the path is a symbolic
1097 link, it should not be converted into the object it points to (but
1098 its case or other aspects should be made unique). All other path
1099 components should be converted from symbolic links. This one
1100 exception is required to agree with Tcl's semantics with 'file
1101 delete', 'file rename', 'file copy' operating on symbolic links.
1102 This function may be called with 'nextCheckpoint' either
1103 at the beginning of the path (i.e. zero), at the end of the path, or
1104 at any intermediate file separator in the path. It will never
1105 point to any other arbitrary position in the path. In the last of
1106 the three valid cases, the implementation can assume that the path
1107 up to and including the file separator is known and normalized.
1110 typedef int Tcl_FSNormalizePathProc(
1111 Tcl_Interp *\fIinterp\fR,
1112 Tcl_Obj *\fIpathPtr\fR,
1113 int \fInextCheckpoint\fR);
1115 .SH "FILESYSTEM OPERATIONS"
1117 The fields in this section of the structure contain addresses of
1118 functions which are called to carry out the basic filesystem
1119 operations. A filesystem which expects to be used with the complete
1120 standard Tcl command set must implement all of these. If some of
1121 them are not implemented, then certain Tcl commands may fail when
1122 operating on paths within that filesystem. However, in some instances
1123 this may be desirable (for example, a read-only filesystem should not
1124 implement the last four functions, and a filesystem which does not
1125 support symbolic links need not implement the \fBreadlink\fR function,
1126 etc. The Tcl core expects filesystems to behave in this way).
1127 .SH FILESYSTEMPATHTYPEPROC
1129 Function to determine the type of a path in this filesystem. May be
1130 NULL, in which case no type information will be available to users of
1131 the filesystem. The 'type' is used only for informational purposes,
1132 and should be returned as the string representation of the Tcl_Obj
1133 which is returned. A typical return value might be "networked", "zip"
1134 or "ftp". The Tcl_Obj result is owned by the filesystem and so Tcl will
1135 increment the refCount of that object if it wishes to retain a reference
1139 typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc(
1140 Tcl_Obj *\fIpathPtr\fR);
1142 .SH FILESYSTEMSEPARATORPROC
1144 Function to return the separator character(s) for this filesystem.
1145 Must be implemented, otherwise the \fBfile separator\fR command will not
1146 function correctly. The usual return value will be a Tcl_Obj
1147 containing the string "/".
1150 typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
1151 Tcl_Obj *\fIpathPtr\fR);
1155 Function to process a \fBTcl_FSStat()\fR call. Must be implemented for any
1156 reasonable filesystem, since many Tcl level commands depend crucially
1157 upon it (e.g. \fBfile atime\fR, \fBfile isdirectory\fR, \fBfile size\fR,
1161 typedef int Tcl_FSStatProc(
1162 Tcl_Obj *\fIpathPtr\fR,
1163 Tcl_StatBuf *\fIstatPtr\fR);
1166 The \fBTcl_FSStatProc\fR fills the stat structure \fIstatPtr\fR with
1167 information about the specified file. You do not need any access
1168 rights to the file to get this information but you need search rights
1169 to all directories named in the path leading to the file. The stat
1170 structure includes info regarding device, inode (always 0 on Windows),
1171 privilege mode, nlink (always 1 on Windows), user id (always 0 on
1172 Windows), group id (always 0 on Windows), rdev (same as device on
1173 Windows), size, last access time, last modification time, and creation
1176 If the file represented by \fIpathPtr\fR exists, the
1177 \fBTcl_FSStatProc\fR returns 0 and the stat structure is filled with
1178 data. Otherwise, -1 is returned, and no stat info is given.
1181 Function to process a \fBTcl_FSAccess()\fR call. Must be implemented for
1182 any reasonable filesystem, since many Tcl level commands depend crucially
1183 upon it (e.g. \fBfile exists\fR, \fBfile readable\fR).
1186 typedef int Tcl_FSAccessProc(
1187 Tcl_Obj *\fIpathPtr\fR,
1191 The \fBTcl_FSAccessProc\fR checks whether the process would be allowed
1192 to read, write or test for existence of the file (or other file system
1193 object) whose name is pathname. If pathname is a symbolic link, then
1194 permissions of the file referred by this symbolic link should be tested.
1196 On success (all requested permissions granted), zero is returned. On
1197 error (at least one bit in mode asked for a permission that is denied,
1198 or some other error occurred), -1 is returned.
1200 .SH OPENFILECHANNELPROC
1202 Function to process a \fBTcl_FSOpenFileChannel()\fR call. Must be
1203 implemented for any reasonable filesystem, since any operations
1204 which require open or accessing a file's contents will use it
1205 (e.g. \fBopen\fR, \fBencoding\fR, and many Tk commands).
1208 typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
1209 Tcl_Interp *\fIinterp\fR,
1210 Tcl_Obj *\fIpathPtr\fR,
1212 int \fIpermissions\fR);
1215 The \fBTcl_FSOpenFileChannelProc\fR opens a file specified by
1216 \fIpathPtr\fR and returns a channel handle that can be used to perform
1217 input and output on the file. This API is modeled after the \fBfopen\fR
1218 procedure of the Unix standard I/O library. The syntax and meaning of
1219 all arguments is similar to those given in the Tcl \fBopen\fR command
1220 when opening a file, where the \fImode\fR argument is a combination of
1221 the POSIX flags O_RDONLY, O_WRONLY, etc. If an error occurs while
1222 opening the channel, the \fBTcl_FSOpenFileChannelProc\fR returns NULL and
1223 records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
1224 In addition, if \fIinterp\fR is non-NULL, the
1225 \fBTcl_FSOpenFileChannelProc\fR leaves an error message in \fIinterp\fR's
1226 result after any error.
1228 The newly created channel is not registered in the supplied
1229 interpreter; to register it, use \fBTcl_RegisterChannel\fR. If one of
1230 the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
1231 previously closed, the act of creating the new channel also assigns it
1232 as a replacement for the standard channel.
1233 .SH MATCHINDIRECTORYPROC
1235 Function to process a \fBTcl_FSMatchInDirectory()\fR call. If not
1236 implemented, then glob and recursive copy functionality will be lacking
1237 in the filesystem (and this may impact commands like 'encoding names'
1238 which use glob functionality internally).
1241 typedef int Tcl_FSMatchInDirectoryProc(
1242 Tcl_Interp* \fIinterp\fR,
1243 Tcl_Obj *\fIresult\fR,
1244 Tcl_Obj *\fIpathPtr\fR,
1245 CONST char *\fIpattern\fR,
1246 Tcl_GlobTypeData * \fItypes\fR);
1249 The function should return all files or directories (or other filesystem
1250 objects) which match the given pattern and accord with the \fItypes\fR
1251 specification given. There are two ways in which this function may be
1252 called. If \fIpattern\fR is NULL, then \fIpathPtr\fR is a full path
1253 specification of a single file or directory which should be checked for
1254 existence and correct type. Otherwise, \fIpathPtr\fR is a directory, the
1255 contents of which the function should search for files or directories
1256 which have the correct type. In either case, \fIpathPtr\fR can be
1257 assumed to be both non-NULL and non-empty. It is not currently
1258 documented whether \fIpathPtr\fR will have a file separator at its end of
1259 not, so code should be flexible to both possibilities.
1261 The return value is a standard Tcl result indicating whether an error
1262 occurred in the matching process. Error messages are placed in interp,
1263 but on a TCL_OK result, the interpreter should not be modified, but
1264 rather results should be added to the \fIresult\fR object given
1265 (which can be assumed to be a valid Tcl list). The matches added
1266 to \fIresult\fR should include any path prefix given in \fIpathPtr\fR
1267 (this usually means they will be absolute path specifications).
1268 Note that if no matches are found, that simply leads to an empty
1269 result --- errors are only signaled for actual file or filesystem
1270 problems which may occur during the matching process.
1273 Function to process a \fBTcl_FSUtime()\fR call. Required to allow setting
1274 (not reading) of times with 'file mtime', 'file atime' and the
1275 open-r/open-w/fcopy implementation of 'file copy'.
1278 typedef int Tcl_FSUtimeProc(
1279 Tcl_Obj *\fIpathPtr\fR,
1280 struct utimbuf *\fItval\fR);
1283 The access and modification times of the file specified by \fIpathPtr\fR
1284 should be changed to the values given in the \fItval\fR structure.
1286 The return value is a standard Tcl result indicating whether an error
1287 occurred in the process.
1290 Function to process a \fBTcl_FSLink()\fR call. Should be implemented
1291 only if the filesystem supports links, and may otherwise be NULL.
1294 typedef Tcl_Obj* Tcl_FSLinkProc(
1295 Tcl_Obj *\fIlinkNamePtr\fR,
1296 Tcl_Obj *\fItoPtr\fR,
1297 int \fIlinkAction\fR);
1300 If \fItoPtr\fR is NULL, the function is being asked to read the
1301 contents of a link. The result is a Tcl_Obj specifying the contents of
1302 the link given by \fIlinkNamePtr\fR, or NULL if the link could
1303 not be read. The result is owned by the caller, which should call
1304 Tcl_DecrRefCount when the result is no longer needed. If \fItoPtr\fR
1305 is not NULL, the function should attempt to create a link. The result
1306 in this case should be \fItoPtr\fR if the link was successful and NULL
1307 otherwise. In this case the result is not owned by the caller. See
1308 the documentation for \fBTcl_FSLink\fR for the correct interpretation
1309 of the \fIlinkAction\fR flags.
1312 Function to list any filesystem volumes added by this filesystem.
1313 Should be implemented only if the filesystem adds volumes at the head
1314 of the filesystem, so that they can be returned by 'file volumes'.
1317 typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
1320 The result should be a list of volumes added by this filesystem, or
1321 NULL (or an empty list) if no volumes are provided. The result object
1322 is considered to be owned by the filesystem (not by Tcl's core), but
1323 should be given a refCount for Tcl. Tcl will use the contents of the
1324 list and then decrement that refCount. This allows filesystems to
1325 choose whether they actually want to retain a 'master list' of volumes
1326 or not (if not, they generate the list on the fly and pass it to Tcl
1327 with a refCount of 1 and then forget about the list, if yes, then
1328 they simply increment the refCount of their master list and pass it
1329 to Tcl which will copy the contents and then decrement the count back
1332 Therefore, Tcl considers return values from this proc to be read-only.
1334 .SH FILEATTRSTRINGSPROC
1336 Function to list all attribute strings which are valid for this
1337 filesystem. If not implemented the filesystem will not support
1338 the \fBfile attributes\fR command. This allows arbitrary additional
1339 information to be attached to files in the filesystem. If it is
1340 not implemented, there is no need to implement the \fBget\fR and \fBset\fR
1344 typedef CONST char** Tcl_FSFileAttrStringsProc(
1345 Tcl_Obj *\fIpathPtr\fR,
1346 Tcl_Obj** \fIobjPtrRef\fR);
1349 The called function may either return an array of strings, or may
1350 instead return NULL and place a Tcl list into the given objPtrRef. Tcl
1351 will take that list and first increment its refCount before using it.
1352 On completion of that use, Tcl will decrement its refCount. Hence if
1353 the list should be disposed of by Tcl when done, it should have a
1354 refCount of zero, and if the list should not be disposed of, the
1355 filesystem should ensure it retains a refCount on the object.
1356 .SH FILEATTRSGETPROC
1358 Function to process a \fBTcl_FSFileAttrsGet()\fR call, used by 'file
1362 typedef int Tcl_FSFileAttrsGetProc(
1363 Tcl_Interp *\fIinterp\fR,
1365 Tcl_Obj *\fIpathPtr\fR,
1366 Tcl_Obj **\fIobjPtrRef\fR);
1369 Returns a standard Tcl return code. The attribute value retrieved,
1370 which corresponds to the \fIindex\fR'th element in the list returned by
1371 the Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if
1372 TCL_OK was returned) and is likely to have a refCount of zero. Either
1373 way we must either store it somewhere (e.g. the Tcl result), or
1374 Incr/Decr its refCount to ensure it is properly freed.
1375 .SH FILEATTRSSETPROC
1377 Function to process a \fBTcl_FSFileAttrsSet()\fR call, used by 'file
1378 attributes'. If the filesystem is read-only, there is no need
1382 typedef int Tcl_FSFileAttrsSetProc(
1383 Tcl_Interp *\fIinterp\fR,
1385 Tcl_Obj *\fIpathPtr\fR,
1386 Tcl_Obj *\fIobjPtr\fR);
1389 The attribute value of the \fIindex\fR'th element in the list returned by
1390 the Tcl_FSFileAttrStringsProc should be set to the \fIobjPtr\fR given.
1391 .SH CREATEDIRECTORYPROC
1393 Function to process a \fBTcl_FSCreateDirectory()\fR call. Should be
1394 implemented unless the FS is read-only.
1397 typedef int Tcl_FSCreateDirectoryProc(
1398 Tcl_Obj *\fIpathPtr\fR);
1401 The return value is a standard Tcl result indicating whether an error
1402 occurred in the process. If successful, a new directory should have
1403 been added to the filesystem in the location specified by
1405 .SH REMOVEDIRECTORYPROC
1407 Function to process a 'Tcl_FSRemoveDirectory()' call. Should be
1408 implemented unless the FS is read-only.
1411 typedef int Tcl_FSRemoveDirectoryProc(
1412 Tcl_Obj *\fIpathPtr\fR,
1413 int \fIrecursive\fR,
1414 Tcl_Obj **\fIerrorPtr\fR);
1417 The return value is a standard Tcl result indicating whether an error
1418 occurred in the process. If successful, the directory specified by
1419 \fIpathPtr\fR should have been removed from the filesystem. If the
1420 \fIrecursive\fR flag is given, then a non-empty directory should
1421 be deleted without error. If an error does occur, the name of
1422 the file or directory which caused the error should be placed in
1426 Function to process a \fBTcl_FSDeleteFile()\fR call. Should be implemented
1427 unless the FS is read-only.
1430 typedef int Tcl_FSDeleteFileProc(
1431 Tcl_Obj *\fIpathPtr\fR);
1434 The return value is a standard Tcl result indicating whether an error
1435 occurred in the process. If successful, the file specified by
1436 \fIpathPtr\fR should have been removed from the filesystem. Note that,
1437 if the filesystem supports symbolic links, Tcl will always call this
1438 function and not Tcl_FSRemoveDirectoryProc when needed to delete them
1439 (even if they are symbolic links to directories).
1440 .SH "FILESYSTEM EFFICIENCY"
1444 Function to process a \fBTcl_FSLstat()\fR call. If not implemented, Tcl
1445 will attempt to use the \fIstatProc\fR defined above instead. Therefore
1446 it need only be implemented if a filesystem can differentiate between
1447 \fBstat\fR and \fBlstat\fR calls.
1450 typedef int Tcl_FSLstatProc(
1451 Tcl_Obj *\fIpathPtr\fR,
1452 Tcl_StatBuf *\fIstatPtr\fR);
1455 The behavior of this function is very similar to that of the
1456 Tcl_FSStatProc defined above, except that if it is applied
1457 to a symbolic link, it returns information about the link, not
1458 about the target file.
1462 Function to process a \fBTcl_FSCopyFile()\fR call. If not implemented Tcl
1463 will fall back on open-r, open-w and fcopy as a copying mechanism.
1464 Therefore it need only be implemented if the filesystem can perform
1465 that action more efficiently.
1468 typedef int Tcl_FSCopyFileProc(
1469 Tcl_Obj *\fIsrcPathPtr\fR,
1470 Tcl_Obj *\fIdestPathPtr\fR);
1473 The return value is a standard Tcl result indicating whether an error
1474 occurred in the copying process. Note that, \fIdestPathPtr\fR is the
1475 name of the file which should become the copy of \fIsrcPathPtr\fR. It
1476 is never the name of a directory into which \fIsrcPathPtr\fR could be
1477 copied (i.e. the function is much simpler than the Tcl level 'file
1478 copy' subcommand). Note that,
1479 if the filesystem supports symbolic links, Tcl will always call this
1480 function and not Tcl_FSCopyDirectoryProc when needed to copy them
1481 (even if they are symbolic links to directories).
1484 Function to process a \fBTcl_FSRenameFile()\fR call. If not implemented,
1485 Tcl will fall back on a copy and delete mechanism. Therefore it need
1486 only be implemented if the filesystem can perform that action more
1490 typedef int Tcl_FSRenameFileProc(
1491 Tcl_Obj *\fIsrcPathPtr\fR,
1492 Tcl_Obj *\fIdestPathPtr\fR);
1495 The return value is a standard Tcl result indicating whether an error
1496 occurred in the renaming process.
1497 .SH COPYDIRECTORYPROC
1499 Function to process a \fBTcl_FSCopyDirectory()\fR call. If not
1500 implemented, Tcl will fall back on a recursive create-dir, file copy
1501 mechanism. Therefore it need only be implemented if the filesystem can
1502 perform that action more efficiently.
1505 typedef int Tcl_FSCopyDirectoryProc(
1506 Tcl_Obj *\fIsrcPathPtr\fR,
1507 Tcl_Obj *\fIdestPathPtr\fR,
1508 Tcl_Obj **\fIerrorPtr\fR);
1511 The return value is a standard Tcl result indicating whether an error
1512 occurred in the copying process. If an error does occur, the name of
1513 the file or directory which caused the error should be placed in
1514 \fIerrorPtr\fR. Note that, \fIdestPathPtr\fR is the name of the
1515 directory-name which should become the mirror-image of
1516 \fIsrcPathPtr\fR. It is not the name of a directory into which
1517 \fIsrcPathPtr\fR should be copied (i.e. the function is much simpler
1518 than the Tcl level 'file copy' subcommand).
1521 Function to process a \fBTcl_FSLoadFile()\fR call. If not implemented, Tcl
1522 will fall back on a copy to native-temp followed by a Tcl_FSLoadFile on
1523 that temporary copy. Therefore it need only be implemented if the
1524 filesystem can load code directly, or it can be implemented simply to
1525 return TCL_ERROR to disable load functionality in this filesystem
1529 typedef int Tcl_FSLoadFileProc(
1530 Tcl_Interp * \fIinterp\fR,
1531 Tcl_Obj *\fIpathPtr\fR,
1532 Tcl_LoadHandle * \fIhandlePtr\fR,
1533 Tcl_FSUnloadFileProc * \fIunloadProcPtr\fR);
1536 Returns a standard Tcl completion code. If an error occurs, an error
1537 message is left in the interp's result. The function dynamically loads
1538 a binary code file into memory. On a successful
1539 load, the \fIhandlePtr\fR should be filled with a token for
1540 the dynamically loaded file, and the \fIunloadProcPtr\fR should be
1541 filled in with the address of a procedure. The procedure will be
1542 called with the given Tcl_LoadHandle as its only parameter when Tcl
1543 needs to unload the file.
1546 Function to unload a previously successfully loaded file. If load was
1547 implemented, then this should also be implemented, if there is any
1548 cleanup action required.
1551 typedef void Tcl_FSUnloadFileProc(
1552 Tcl_LoadHandle \fIloadHandle\fR);
1556 Function to process a \fBTcl_FSGetCwd()\fR call. Most filesystems need not
1557 implement this. It will usually only be called once, if 'getcwd' is
1558 called before 'chdir'. May be NULL.
1561 typedef Tcl_Obj* Tcl_FSGetCwdProc(
1562 Tcl_Interp *\fIinterp\fR);
1565 If the filesystem supports a native notion of a current working
1566 directory (which might perhaps change independent of Tcl), this
1567 function should return that cwd as the result, or NULL if the current
1568 directory could not be determined (e.g. the user does not have
1569 appropriate permissions on the cwd directory). If NULL is returned, an
1570 error message is left in the interp's result.
1574 Function to process a \fBTcl_FSChdir()\fR call. If filesystems do not
1575 implement this, it will be emulated by a series of directory access
1576 checks. Otherwise, virtual filesystems which do implement it need only
1577 respond with a positive return result if the dirName is a valid,
1578 accessible directory in their filesystem. They need not remember the
1579 result, since that will be automatically remembered for use by GetCwd.
1580 Real filesystems should carry out the correct action (i.e. call the
1581 correct system 'chdir' api).
1584 typedef int Tcl_FSChdirProc(
1585 Tcl_Obj *\fIpathPtr\fR);
1588 The \fBTcl_FSChdirProc\fR changes the applications current working
1589 directory to the value specified in \fIpathPtr\fR. The function returns
1590 -1 on error or 0 on success.
1592 stat access filesystem vfs
OSDN Git Service
