1Filesystem(3) Tcl Library Procedures Filesystem(3)
2______________________________________________________________________________
6
8 Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged,
9 Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile,
10 Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRe‐
11 moveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile,
12 Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat,
13 Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAt‐
14 trStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel,
15 Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath,
16 Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoin‐
17 ToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTrans‐
18 latedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath,
19 Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_AllocStatBuf - proce‐
20 dures to interact with any filesystem
21
23 #include <tcl.h>
24 int
26 Tcl_FSRegister(clientData, fsPtr)
27 int
29 Tcl_FSUnregister(fsPtr)
30 ClientData
32 Tcl_FSData(fsPtr)
33 void
35 Tcl_FSMountsChanged(fsPtr)
36 Tcl_Filesystem*
38 Tcl_FSGetFileSystemForPath(pathObjPtr)
39 Tcl_PathType
41 Tcl_FSGetPathType(pathObjPtr)
42 int
44 Tcl_FSCopyFile(srcPathPtr, destPathPtr)
45 int
47 Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)
48 int
50 Tcl_FSCreateDirectory(pathPtr)
51 int
53 Tcl_FSDeleteFile(pathPtr)
54 int
56 Tcl_FSRemoveDirectory(pathPtr, int recursive, errorPtr)
57 int
59 Tcl_FSRenameFile(srcPathPtr, destPathPtr)
60 Tcl_Obj*
62 Tcl_FSListVolumes(void)
63 int
65 Tcl_FSEvalFile(interp, pathPtr)
66 int
68 Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
69 handlePtr, unloadProcPtr)
70 int
72 Tcl_FSMatchInDirectory(interp, result, pathPtr, pattern, types)
73 Tcl_Obj*
75 Tcl_FSLink(linkNamePtr, toPtr, linkAction)
76 int
78 Tcl_FSLstat(pathPtr, statPtr)
79 int
81 Tcl_FSUtime(pathPtr, tval)
82 int
84 Tcl_FSFileAttrsGet(interp, int index, pathPtr, objPtrRef)
85 int
87 Tcl_FSFileAttrsSet(interp, int index, pathPtr, Tcl_Obj *objPtr)
88 CONST char**
90 Tcl_FSFileAttrStrings(pathPtr, objPtrRef)
91 int
93 Tcl_FSStat(pathPtr, statPtr)
94 int
96 Tcl_FSAccess(pathPtr, mode)
97 Tcl_Channel
99 Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)
100 Tcl_Obj*
102 Tcl_FSGetCwd(interp)
103 int
105 Tcl_FSChdir(pathPtr)
106 Tcl_Obj*
108 Tcl_FSPathSeparator(pathPtr)
109 Tcl_Obj*
111 Tcl_FSJoinPath(listObj, elements)
112 Tcl_Obj*
114 Tcl_FSSplitPath(pathPtr, lenPtr)
115 int
117 Tcl_FSEqualPaths(firstPtr, secondPtr)
118 Tcl_Obj*
120 Tcl_FSGetNormalizedPath(interp, pathPtr)
121 Tcl_Obj*
123 Tcl_FSJoinToPath(basePtr, objc, objv)
124 int
126 Tcl_FSConvertToPathType(interp, pathPtr)
127 ClientData
129 Tcl_FSGetInternalRep(pathPtr, fsPtr)
130 Tcl_Obj*
132 Tcl_FSGetTranslatedPath(interp, pathPtr)
133 CONST char*
135 Tcl_FSGetTranslatedStringPath(interp, pathPtr)
136 Tcl_Obj*
138 Tcl_FSNewNativePath(fsPtr, clientData)
139 CONST char*
141 Tcl_FSGetNativePath(pathPtr)
142 Tcl_Obj*
144 Tcl_FSFileSystemInfo(pathPtr)
145 Tcl_StatBuf*
147 Tcl_AllocStatBuf()
148
150 Tcl_Filesystem *fsPtr (in) Points to a structure containing
151 the addresses of procedures that
152 can be called to perform the vari‐
153 ous filesystem operations.
154 Tcl_Obj *pathPtr (in) The path represented by this object
156 is used for the operation in ques‐
157 tion. If the object does not
158 already have an internal path rep‐
159 resentation, it will be converted
160 to have one.
161 Tcl_Obj *srcPathPtr(in) As for pathPtr, but used for the
163 source file for a copy or rename
164 operation.
165 Tcl_Obj *destPathPtr(in) As for pathPtr, but used for the
167 destination filename for a copy or
168 rename operation.
169 CONST char *pattern (in) Only files or directories matching
171 this pattern will be returned by
172 Tcl_FSMatchInDirectory.
173 GlobTypeData *types (in) Only files or directories matching
175 the type descriptions contained in
176 this structure will be returned by
177 Tcl_FSMatchInDirectory. It is very
178 important that the 'directory' flag
179 is properly handled. This parame‐
180 ter may be NULL.
181 Tcl_Interp *interp (in) Interpreter to use either for
183 results, evaluation, or reporting
184 error messages.
185 ClientData clientData(in) The native description of the path
187 object to create.
188 Tcl_Obj *firstPtr(in) The first of two path objects to
190 compare. The object may be con‐
191 verted to path type.
192 Tcl_Obj *secondPtr(in) The second of two path objects to
194 compare. The object may be con‐
195 verted to path type.
196 Tcl_Obj *listObj (in) The list of path elements to oper‐
198 ate on with a join operation.
199 int elements (in) If non-negative, the number of ele‐
201 ments in the listObj which should
202 be joined together. If negative,
203 then all elements are joined.
204 Tcl_Obj **errorPtr(out) In the case of an error, filled
206 with an object containing the name
207 of the file which caused an error
208 in the various copy/rename opera‐
209 tions.
210 Tcl_Obj **objPtrRef(out) Filled with an object containing
212 the result of the operation.
213 Tcl_Obj *result (out) Pre-allocated object in which to
215 store (by lappending) the list of
216 files or directories which are suc‐
217 cessfully matched in
218 Tcl_FSMatchInDirectory.
219 int mode (in) Mask consisting of one or more of
221 R_OK, W_OK, X_OK and F_OK. R_OK,
222 W_OK and X_OK request checking
223 whether the file exists and has
224 read, write and execute permis‐
225 sions, respectively. F_OK just
226 requests checking for the existence
227 of the file.
228 Tcl_StatBuf *statPtr (out) The structure that contains the
230 result of a stat or lstat opera‐
231 tion.
232 CONST char *sym1 (in) Name of a procedure to look up in
234 the file's symbol table
235 CONST char *sym2 (in) Name of a procedure to look up in
237 the file's symbol table
238 Tcl_PackageInitProc **proc1Ptr(out)
240 Filled with the init function for
241 this code.
242 Tcl_PackageInitProc **proc2Ptr(out)
244 Filled with the safe-init function
245 for this code.
246 Tcl_LoadHandle *handlePtr(out) Filled with an abstract token rep‐
248 resenting the loaded file.
249 ClientData *clientDataPtr(out)
251 Filled with the clientData value to
252 pass to this code's unload function
253 when it is called.
254 TclfsUnloadFileProc_ **unloadProcPtr(out)
256 Filled with the function to use to
257 unload this piece of code.
258 utimbuf *tval (in) The access and modification times
260 in this structure are read and used
261 to set those values for a given
262 file.
263 CONST char *modeString(in) Specifies how the file is to be
265 accessed. May have any of the val‐
266 ues allowed for the mode argument
267 to the Tcl open command.
268 int permissions(in) POSIX-style permission flags such
270 as 0644. If a new file is created,
271 these permissions will be set on
272 the created file.
273 int *lenPtr (out) If non-NULL, filled with the number
275 of elements in the split path.
276 Tcl_Obj *basePtr (in) The base path on to which to join
278 the given elements. May be NULL.
279 int objc (in) The number of elements in objv.
281 Tcl_Obj *CONST objv[] (in) The elements to join to the given
283 base path.
284_________________________________________________________________
285
288 There are several reasons for calling the Tcl_FS... functions rather
289 than calling system level functions like access and stat directly.
290 First, they will work cross-platform, so an extension which calls them
291 should work unmodified on Unix, MacOS and Windows. Second, the Windows
292 implementation of some of these functions fixes some bugs in the system
293 level calls. Third, these function calls deal with any 'Utf to plat‐
294 form-native' path conversions which may be required (and may cache the
295 results of such conversions for greater efficiency on subsequent
296 calls). Fourth, and perhaps most importantly, all of these functions
297 are 'virtual filesystem aware'. Any virtual filesystem which has been
298 registered (through Tcl_FSRegister) may reroute file access to alterna‐
299 tive media or access methods. This means that all of these functions
300 (and therefore the corresponding file, glob, pwd, cd, open, etc. Tcl
301 commands) may be operate on 'files' which are not native files in the
302 native filesystem. This also means that any Tcl extension which
303 accesses the filesystem through this API is automatically 'virtual
304 filesystem aware'. Of course, if an extension accesses the native
305 filesystem directly (through platform-specific APIs, for example), then
306 Tcl cannot intercept such calls.
307 If appropriate vfs's have been registered, the 'files' may, to give two
309 examples, be remote (e.g. situated on a remote ftp server) or archived
310 (e.g. lying inside a .zip archive). Such registered filesystems pro‐
311 vide a lookup table of functions to implement all or some of the func‐
312 tionality listed here. Finally, the Tcl_FSStat and Tcl_FSLstat calls
313 abstract away from what the 'struct stat' buffer buffer is actually
314 declared to be, allowing the same code to be used both on systems with
315 and systems without support for files larger than 2GB in size.
316 The Tcl_FS... are objectified and may cache internal representations
318 and other path-related strings (e.g. the current working directory).
319 One side-effect of this is that one must not pass in objects with a
320 refCount of zero to any of these functions. If such calls were han‐
321 dled, they might result in memory leaks (under some circumstances, the
322 filesystem code may wish to retain a reference to the passed in object,
323 and so one must not assume that after any of these calls return, the
324 object still has a refCount of zero - it may have been incremented), or
325 in a direct segfault due to the object being freed part way through the
326 complex object manipulation required to ensure that the path is fully
327 normalized and absolute for filesystem determination. The practical
328 lesson to learn from this is that Tcl_Obj *path = Tcl_NewStringObj(...)
329 ; Tcl_FS...(path) ; Tcl_DecrRefCount(path) is wrong, and may segfault.
330 The 'path' must have its refCount incremented before passing it in, or
331 decrementing it. For this reason, objects with a refCount of zero are
332 considered not to be valid filesystem paths and calling any Tcl_FS API
333 with such an object will result in no action being taken.
334 Tcl_FSCopyFile attempts to copy the file given by srcPathPtr to the
336 path name given by destPathPtr. If the two paths given lie in the same
337 filesystem (according to Tcl_FSGetFileSystemForPath) then that filesys‐
338 tem's 'copy file' function is called (if it is non-NULL). Otherwise
339 the function returns -1 and sets Tcl's errno to the 'EXDEV' posix error
340 code (which signifies a 'cross-domain link').
341 Tcl_FSCopyDirectory attempts to copy the directory given by srcPathPtr
343 to the path name given by destPathPtr. If the two paths given lie in
344 the same filesystem (according to Tcl_FSGetFileSystemForPath) then that
345 filesystem's 'copy file' function is called (if it is non-NULL). Oth‐
346 erwise the function returns -1 and sets Tcl's errno to the 'EXDEV'
347 posix error code (which signifies a 'cross-domain link').
348 Tcl_FSCreateDirectory attempts to create the directory given by pathPtr
350 by calling the owning filesystem's 'create directory' function.
351 Tcl_FSDeleteFile attempts to delete the file given by pathPtr by call‐
353 ing the owning filesystem's 'delete file' function.
354 Tcl_FSRemoveDirectory attempts to remove the directory given by pathPtr
356 by calling the owning filesystem's 'remove directory' function.
357 Tcl_FSRenameFile attempts to rename the file or directory given by src‐
359 PathPtr to the path name given by destPathPtr. If the two paths given
360 lie in the same filesystem (according to Tcl_FSGetFileSystemForPath)
361 then that filesystem's 'rename file' function is called (if it is non-
362 NULL). Otherwise the function returns -1 and sets Tcl's errno to the
363 'EXDEV' posix error code (which signifies a ``cross-domain link'').
364 Tcl_FSListVolumes calls each filesystem which has a non-NULL 'list vol‐
366 umes' function and asks them to return their list of root volumes. It
367 accumulates the return values in a list which is returned to the caller
368 (with a refCount of 0).
369 Tcl_FSEvalFile reads the file given by pathPtr and evaluates its con‐
371 tents as a Tcl script. It returns the same information as Tcl_EvalOb‐
372 jEx. If the file couldn't be read then a Tcl error is returned to
373 describe why the file couldn't be read. The eofchar for files is '\32'
374 (^Z) for all platforms. If you require a ``^Z'' in code for string
375 comparison, you can use ``\032'' or ``\u001a'', which will be safely
376 substituted by the Tcl interpreter into ``^Z''.
377 Tcl_FSLoadFile dynamically loads a binary code file into memory and
379 returns the addresses of two procedures within that file, if they are
380 defined. The appropriate function for the filesystem to which pathPtr
381 belongs will be called. If that filesystem does not implement this
382 function (most virtual filesystems will not, because of OS limitations
383 in dynamically loading binary code), Tcl will attempt to copy the file
384 to a temporary directory and load that temporary file.
385 Returns a standard Tcl completion code. If an error occurs, an error
387 message is left in the interp's result.
388 Tcl_FSMatchInDirectory is used by the globbing code to search a direc‐
390 tory for all files which match a given pattern. The appropriate func‐
391 tion for the filesystem to which pathPtr belongs will be called.
392 The return value is a standard Tcl result indicating whether an error
394 occurred in globbing. Error messages are placed in interp, but good
395 results are placed in the resultPtr given.
396 Note that the 'glob' code implements recursive pat‐
397 terns internally, so this function will only ever be passed simple pat‐
398 terns, which can be matched using the logic of 'string match'. To han‐
399 dle recursion, Tcl will call this function frequently asking only for
400 directories to be returned.
401 Tcl_FSLink replaces the library version of readlink(), and extends it
403 to support the creation of links. The appropriate function for the
404 filesystem to which linkNamePtr belongs will be called.
405 If the toPtr is NULL, a readlink action is performed. The result is a
407 Tcl_Obj specifying the contents of the symbolic link given by
408 linkNamePtr, or NULL if the link could not be read. The result is
409 owned by the caller, which should call Tcl_DecrRefCount when the result
410 is no longer needed. If the toPtr is not NULL, Tcl should create a
411 link of one of the types passed in in the linkAction flag. This flag
412 is an or'd combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CRE‐
413 ATE_HARD_LINK. Where a choice exists (i.e. more than one flag is
414 passed in), the Tcl convention is to prefer symbolic links. When a
415 link is successfully created, the return value should be toPtr (which
416 is therefore already owned by the caller). If unsuccessful, NULL
417 should be returned.
418 Tcl_FSLstat fills the stat structure statPtr with information about the
420 specified file. You do not need any access rights to the file to get
421 this information but you need search rights to all directories named in
422 the path leading to the file. The stat structure includes info regard‐
423 ing device, inode (always 0 on Windows), privilege mode, nlink (always
424 1 on Windows), user id (always 0 on Windows), group id (always 0 on
425 Windows), rdev (same as device on Windows), size, last access time,
426 last modification time, and creation time.
427 If path exists, Tcl_FSLstat returns 0 and the stat structure is filled
429 with data. Otherwise, -1 is returned, and no stat info is given.
430 Tcl_FSUtime replaces the library version of utime.
432 For results see 'utime' documentation. If successful, the function
434 will update the 'atime' and 'mtime' values of the file given.
435 Tcl_FSFileAttrsGet implements read access for the hookable 'file
437 attributes' subcommand. The appropriate function for the filesystem to
438 which pathPtr belongs will be called.
439 If the result is TCL_OK, then an object was placed in objPtrRef, which
441 will only be temporarily valid (unless Tcl_IncrRefCount is called).
442 Tcl_FSFileAttrsSet implements write access for the hookable 'file
444 attributes' subcommand. The appropriate function for the filesystem to
445 which pathPtr belongs will be called.
446 Tcl_FSFileAttrStrings implements part of the hookable 'file attributes'
448 subcommand. The appropriate function for the filesystem to which path‐
449 Ptr belongs will be called.
450 The called procedure may either return an array of strings, or may
452 instead return NULL and place a Tcl list into the given objPtrRef. Tcl
453 will take that list and first increment its refCount before using it.
454 On completion of that use, Tcl will decrement its refCount. Hence if
455 the list should be disposed of by Tcl when done, it should have a ref‐
456 Count of zero, and if the list should not be disposed of, the filesys‐
457 tem should ensure it retains a refCount on the object.
458 Tcl_FSAccess checks whether the process would be allowed to read, write
460 or test for existence of the file (or other file system object) whose
461 name is pathname. If pathname is a symbolic link on Unix, then per‐
462 missions of the file referred by this symbolic link are tested.
463 On success (all requested permissions granted), zero is returned. On
465 error (at least one bit in mode asked for a permission that is denied,
466 or some other error occurred), -1 is returned.
467 Tcl_FSStat fills the stat structure statPtr with information about the
469 specified file. You do not need any access rights to the file to get
470 this information but you need search rights to all directories named in
471 the path leading to the file. The stat structure includes info regard‐
472 ing device, inode (always 0 on Windows), privilege mode, nlink (always
473 1 on Windows), user id (always 0 on Windows), group id (always 0 on
474 Windows), rdev (same as device on Windows), size, last access time,
475 last modification time, and creation time.
476 If path exists, Tcl_FSStat returns 0 and the stat structure is filled
478 with data. Otherwise, -1 is returned, and no stat info is given.
479 Tcl_FSOpenFileChannel opens a file specified by pathPtr and returns a
481 channel handle that can be used to perform input and output on the
482 file. This API is modeled after the fopen procedure of the Unix stan‐
483 dard I/O library. The syntax and meaning of all arguments is similar
484 to those given in the Tcl open command when opening a file. If an
485 error occurs while opening the channel, Tcl_FSOpenFileChannel returns
486 NULL and records a POSIX error code that can be retrieved with
487 Tcl_GetErrno. In addition, if interp is non-NULL, Tcl_FSOpenFileChan‐
488 nel leaves an error message in interp's result after any error.
489 The newly created channel is not registered in the supplied inter‐
491 preter; to register it, use Tcl_RegisterChannel, described below. If
492 one of the standard channels, stdin, stdout or stderr was previously
493 closed, the act of creating the new channel also assigns it as a
494 replacement for the standard channel.
495 Tcl_FSGetCwd replaces the library version of getcwd().
497 It returns the Tcl library's current working directory. This may be
499 different to the native platform's working directory, in the case for
500 which the cwd is not in the native filesystem.
501 The result is a pointer to a Tcl_Obj specifying the current directory,
503 or NULL if the current directory could not be determined. If NULL is
504 returned, an error message is left in the interp's result.
505 The result already has its refCount incremented for
506 the caller. When it is no longer needed, that refCount should be
507 decremented. This is needed for thread-safety purposes, to allow mul‐
508 tiple threads to access this and related functions, while ensuring the
509 results are always valid.
510 Tcl_FSChdir replaces the library version of chdir(). The path is nor‐
512 malized and then passed to the filesystem which claims it. If that
513 filesystem does not implement this function, Tcl will fallback to a
514 combination of stat and access to check whether the directory exists
515 and has appropriate permissions.
516 For results, see chdir() documentation. If successful, we keep a
518 record of the successful path in cwdPathPtr for subsequent calls to
519 getcwd.
520 Tcl_FSPathSeparator returns the separator character to be used for most
522 specific element of the path specified by pathPtr (i.e. the last part
523 of the path).
524 The separator is returned as a Tcl_Obj containing a string of length 1.
526 If the path is invalid, NULL is returned.
527 Tcl_FSJoinPath takes the given Tcl_Obj, which should be a valid list,
529 and returns the path object given by considering the first 'elements'
530 elements as valid path segments. If elements < 0, we use the entire
531 list.
532 Returns object with refCount of zero, containing the joined path.
534 Tcl_FSSplitPath takes the given Tcl_Obj, which should be a valid path,
536 and returns a Tcl List object containing each segment of that path as
537 an element.
538 Returns list object with refCount of zero. If the passed in lenPtr is
540 non-NULL, we use it to return the number of elements in the returned
541 list.
542 Tcl_FSEqualPaths tests whether the two paths given represent the same
544 filesystem object
545 It returns 1 if the paths are equal, and 0 if they are different. If
547 either path is NULL, 0 is always returned.
548 Tcl_FSGetNormalizedPath this important function attempts to extract
550 from the given Tcl_Obj a unique normalized path representation, whose
551 string value can be used as a unique identifier for the file.
552 It returns the normalized path object, with refCount of zero, or NULL
554 if the path was invalid or could otherwise not be successfully con‐
555 verted. Extraction of absolute, normalized paths is very efficient
556 (because the filesystem operates on these representations internally),
557 although the result when the filesystem contains numerous symbolic
558 links may not be the most user-friendly version of a path.
559 Tcl_FSJoinToPath takes the given object, which should usually be a
561 valid path or NULL, and joins onto it the array of paths segments
562 given.
563 Returns object with refCount of zero, containing the joined path.
565 Tcl_FSConvertToPathType tries to convert the given Tcl_Obj to a valid
567 Tcl path type, taking account of the fact that the cwd may have changed
568 even if this object is already supposedly of the correct type. The
569 filename may begin with "~" (to indicate current user's home directory)
570 or "~<user>" (to indicate any user's home directory).
571 If the conversion succeeds (i.e. the object is a valid path in one of
573 the current filesystems), then TCL_OK is returned. Otherwise TCL_ERROR
574 is returned, and an error message may be left in the interpreter.
575 Tcl_FSGetInternalRep extracts the internal representation of a given
577 path object, in the given filesystem. If the path object belongs to a
578 different filesystem, we return NULL. If the internal representation is
579 currently NULL, we attempt to generate it, by calling the filesystem's
580 Tcl_FSCreateInternalRepProc.
581 Returns NULL or a valid internal path representation. This internal
583 representation is cached, so that repeated calls to this function will
584 not require additional conversions.
585 Tcl_FSGetTranslatedPath attempts to extract the translated path from
587 the given Tcl_Obj.
588 If the translation succeeds (i.e. the object is a valid path), then it
590 is returned. Otherwise NULL will be returned, and an error message may
591 be left in the interpreter. A "translated" path is one which contains
592 no "~" or "~user" sequences (these have been expanded to their current
593 representation in the filesystem). The object returned is owned by the
594 caller, which must store it or call Tcl_DecrRefCount to ensure memory
595 is freed. This function is of little practical use, and Tcl_FSGetNor‐
596 malizedPath or Tcl_GetNativePath are usually better functions to use
597 for most purposes.
598 Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
600 but returns a character string or NULL. The string returned is dynami‐
601 cally allocated and owned by the caller, which must store it or call
602 ckfree to ensure it is freed. Again, Tcl_FSGetNormalizedPath or
603 Tcl_GetNativePath are usually better functions to use for most pur‐
604 poses.
605 Tcl_FSNewNativePath performs something like that reverse of the usual
607 obj->path->nativerep conversions. If some code retrieves a path in
608 native form (from, e.g. readlink or a native dialog), and that path is
609 to be used at the Tcl level, then calling this function is an efficient
610 way of creating the appropriate path object type.
611 The resulting object is a pure 'path' object, which will only receive a
613 Utf-8 string representation if that is required by some Tcl code.
614 Tcl_FSGetNativePath is for use by the Win/Unix/MacOS native filesys‐
616 tems, so that they can easily retrieve the native (char* or TCHAR*)
617 representation of a path. This function is a convenience wrapper
618 around Tcl_FSGetInternalRep, and assumes the native representation is
619 string-based. It may be desirable in the future to have non-string-
620 based native representations (for example, on MacOS, a representation
621 using a fileSpec of FSRef structure would probably be more efficient).
622 On Windows a full Unicode representation would allow for paths of
623 unlimited length. Currently the representation is simply a character
624 string containing the complete, absolute path in the native encoding.
625 The native representation is cached so that repeated calls to this
627 function will not require additional conversions.
628 Tcl_FSFileSystemInfo returns a list of two elements. The first element
630 is the name of the filesystem (e.g. "native" or "vfs" or "zip" or
631 "prowrap", perhaps), and the second is the particular type of the given
632 path within that filesystem (which is filesystem dependent). The sec‐
633 ond element may be empty if the filesystem does not provide a further
634 categorization of files.
635 A valid list object is returned, unless the path object is not recog‐
637 nized, when NULL will be returned.
638 Tcl_FSGetFileSystemForPath returns the a pointer to the Tcl_Filesystem
640 which accepts this path as valid.
641 If no filesystem will accept the path, NULL is returned.
643 Tcl_FSGetPathType determines whether the given path is relative to the
645 current directory, relative to the current volume, or absolute.
646 It returns one of TCL_PATH_ABSOLUTE, TCL_PATH_RELATIVE, or
648 TCL_PATH_VOLUME_RELATIVE
649 Tcl_AllocStatBuf allocates a Tcl_StatBuf on the system heap (which may
651 be deallocated by being passed to ckfree.) This allows extensions to
652 invoke Tcl_FSStat and Tcl_FSLStat without being dependent on the size
653 of the buffer. That in turn depends on the flags used to build Tcl.
654
656 A filesystem provides a Tcl_Filesystem structure that contains pointers
657 to functions that implement the various operations on a filesystem;
658 these operations are invoked as needed by the generic layer, which gen‐
659 erally occurs through the functions listed above.
660 The Tcl_Filesystem structures are manipulated using the following meth‐
662 ods.
663 Tcl_FSRegister takes a pointer to a filesystem structure and an
665 optional piece of data to associated with that filesystem. On calling
666 this function, Tcl will attach the filesystem to the list of known
667 filesystems, and it will become fully functional immediately. Tcl does
668 not check if the same filesystem is registered multiple times (and in
669 general that is not a good thing to do). TCL_OK will be returned.
670 Tcl_FSUnregister removes the given filesystem structure from the list
672 of known filesystems, if it is known, and returns TCL_OK. If the
673 filesystem is not currently registered, TCL_ERROR is returned.
674 Tcl_FSData will return the ClientData associated with the given
676 filesystem, if that filesystem is registered. Otherwise it will return
677 NULL.
678 Tcl_FSMountsChanged is used to inform the Tcl's core that the set of
680 mount points for the given (already registered) filesystem have
681 changed, and that cached file representations may therefore no longer
682 be correct.
683 The Tcl_Filesystem structure contains the following fields:
685 typedef struct Tcl_Filesystem {
686 CONST char *typeName;
687 int structureLength;
688 Tcl_FSVersion version;
689 Tcl_FSPathInFilesystemProc *pathInFilesystemProc;
690 Tcl_FSDupInternalRepProc *dupInternalRepProc;
691 Tcl_FSFreeInternalRepProc *freeInternalRepProc;
692 Tcl_FSInternalToNormalizedProc *internalToNormalizedProc;
693 Tcl_FSCreateInternalRepProc *createInternalRepProc;
694 Tcl_FSNormalizePathProc *normalizePathProc;
695 Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc;
696 Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc;
697 Tcl_FSStatProc *statProc;
698 Tcl_FSAccessProc *accessProc;
699 Tcl_FSOpenFileChannelProc *openFileChannelProc;
700 Tcl_FSMatchInDirectoryProc *matchInDirectoryProc;
701 Tcl_FSUtimeProc *utimeProc;
702 Tcl_FSLinkProc *linkProc;
703 Tcl_FSListVolumesProc *listVolumesProc;
704 Tcl_FSFileAttrStringsProc *fileAttrStringsProc;
705 Tcl_FSFileAttrsGetProc *fileAttrsGetProc;
706 Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
707 Tcl_FSCreateDirectoryProc *createDirectoryProc;
708 Tcl_FSRemoveDirectoryProc *removeDirectoryProc;
709 Tcl_FSDeleteFileProc *deleteFileProc;
710 Tcl_FSCopyFileProc *copyFileProc;
711 Tcl_FSRenameFileProc *renameFileProc;
712 Tcl_FSCopyDirectoryProc *copyDirectoryProc;
713 Tcl_FSLstatProc *lstatProc;
714 Tcl_FSLoadFileProc *loadFileProc;
715 Tcl_FSGetCwdProc *getCwdProc;
716 Tcl_FSChdirProc *chdirProc;
717 } Tcl_Filesystem;
718 Except for the first three fields in this structure which contain sim‐
720 ple data elements, all entries contain addresses of functions called by
721 the generic filesystem layer to perform the complete range of filesys‐
722 tem related actions.
723 The many functions in this structure are broken down into three cate‐
725 gories: infrastructure functions (almost all of which must be imple‐
726 mented), operational functions (which must be implemented if a complete
727 filesystem is provided), and efficiency functions (which need only be
728 implemented if they can be done so efficiently, or if they have side-
729 effects which are required by the filesystem; Tcl has less efficient
730 emulations it can fall back on). It is important to note that, in the
731 current version of Tcl, most of these fallbacks are only used to handle
732 commands initiated in Tcl, not in C. What this means is, that if a
733 'file rename' command is issued in Tcl, and the relevant filesystem(s)
734 do not implement their Tcl_FSRenameFileProc, Tcl's core will instead
735 fallback on a combination of other filesystem functions (it will use
736 Tcl_FSCopyFileProc followed by Tcl_FSDeleteFileProc, and if Tcl_FSCopy‐
737 FileProc is not implemented there is a further fallback). However, if
738 a Tcl_FSRenameFile command is issued at the C level, no such fallbacks
739 occur. This is true except for the last four entries in the filesystem
740 table (lstat, load, getcwd and chdir) for which fallbacks do in fact
741 occur at the C level.
742 As an example, here is the filesystem lookup table used by the "vfs"
744 extension which allows filesystem actions to be implemented in Tcl.
745 static Tcl_Filesystem vfsFilesystem = {
746 "tclvfs",
747 sizeof(Tcl_Filesystem),
748 TCL_FILESYSTEM_VERSION_1,
749 &VfsPathInFilesystem,
750 &VfsDupInternalRep,
751 &VfsFreeInternalRep,
752 /* No internal to normalized, since we don't create any
753 * pure 'internal' Tcl_Obj path representations */
754 NULL,
755 /* No create native rep function, since we don't use it
756 * and don't choose to support uses of 'Tcl_FSNewNativePath' */
757 NULL,
758 /* Normalize path isn't needed - we assume paths only have
759 * one representation */
760 NULL,
761 &VfsFilesystemPathType,
762 &VfsFilesystemSeparator,
763 &VfsStat,
764 &VfsAccess,
765 &VfsOpenFileChannel,
766 &VfsMatchInDirectory,
767 &VfsUtime,
768 /* We choose not to support symbolic links inside our vfs's */
769 NULL,
770 &VfsListVolumes,
771 &VfsFileAttrStrings,
772 &VfsFileAttrsGet,
773 &VfsFileAttrsSet,
774 &VfsCreateDirectory,
775 &VfsRemoveDirectory,
776 &VfsDeleteFile,
777 /* No copy file - fallback will occur at Tcl level */
778 NULL,
779 /* No rename file - fallback will occur at Tcl level */
780 NULL,
781 /* No copy directory - fallback will occur at Tcl level */
782 NULL,
783 /* Core will use stat for lstat */
784 NULL,
785 /* No load - fallback on core implementation */
786 NULL,
787 /* We don't need a getcwd or chdir - fallback on Tcl's versions */
788 NULL,
789 NULL
790 };
791 Any functions which take path names in Tcl_Obj form take those names in
793 UTF-8 form. The filesystem infrastructure API is designed to support
794 efficient, cached conversion of these UTF-8 paths to other native rep‐
795 resentations.
796
798 The typeName field contains a null-terminated string that identifies
799 the type of the filesystem implemented, e.g. native or zip or vfs.
800
802 The structureLength field is generally implemented as
803 sizeof(Tcl_Filesystem), and is there to allow easier binary backwards
804 compatibility if the size of the structure changes in a future Tcl
805 release.
806
808 The version field should be set to TCL_FILESYSTEM_VERSION_1.
809
811 These fields contain addresses of functions which are used to associate
812 a particular filesystem with a file path, and deal with the internal
813 handling of path representations, for example copying and freeing such
814 representations.
815
817 The pathInFilesystemProc field contains the address of a function which
818 is called to determine whether a given path object belongs to this
819 filesystem or not. Tcl will only call the rest of the filesystem func‐
820 tions with a path for which this function has returned TCL_OK. If the
821 path does not belong, -1 should be returned (the behaviour of Tcl for
822 any other return value is not defined). If TCL_OK is returned, then
823 the optional clientDataPtr output parameter can be used to return an
824 internal (filesystem specific) representation of the path, which will
825 be cached inside the path object, and may be retrieved efficiently by
826 the other filesystem functions. Tcl will simultaneously cache the fact
827 that this path belongs to this filesystem. Such caches are invalidated
828 when filesystem structures are added or removed from Tcl's internal
829 list of known filesystems.
830 typedef int Tcl_FSPathInFilesystemProc(
832 Tcl_Obj *pathPtr,
833 ClientData *clientDataPtr);
834
836 This function makes a copy of a path's internal representation, and is
837 called when Tcl needs to duplicate a path object. If NULL, Tcl will
838 simply not copy the internal representation, which may then need to be
839 regenerated later.
840 typedef ClientData Tcl_FSDupInternalRepProc(
842 ClientData clientData);
843
845 Free the internal representation. This must be implemented if internal
846 representations need freeing (i.e. if some memory is allocated when an
847 internal representation is generated), but may otherwise be NULL.
848 typedef void Tcl_FSFreeInternalRepProc(
850 ClientData clientData);
851
853 Function to convert internal representation to a normalized path. Only
854 required if the filesystem creates pure path objects with no
855 string/path representation. The return value is a Tcl object whose
856 string representation is the normalized path.
857 typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
859 ClientData clientData);
860
862 Function to take a path object, and calculate an internal representa‐
863 tion for it, and store that native representation in the object. May
864 be NULL if paths have no internal representation, or if the
865 Tcl_FSPathInFilesystemProc for this filesystem always immediately cre‐
866 ates an internal representation for paths it accepts.
867 typedef ClientData Tcl_FSCreateInternalRepProc(
869 Tcl_Obj *pathPtr);
870
872 Function to normalize a path. Should be implemented for all filesys‐
873 tems which can have multiple string representations for the same path
874 object. In Tcl, every 'path' must have a single unique 'normalized'
875 string representation. Depending on the filesystem, there may be more
876 than one unnormalized string representation which refers to that path
877 (e.g. a relative path, a path with different character case if the
878 filesystem is case insensitive, a path contain a reference to a home
879 directory such as '~', a path containing symbolic links, etc). If the
880 very last component in the path is a symbolic link, it should not be
881 converted into the object it points to (but its case or other aspects
882 should be made unique). All other path components should be converted
883 from symbolic links. This one exception is required to agree with
884 Tcl's semantics with 'file delete', 'file rename', 'file copy' operat‐
885 ing on symbolic links. This function may be called with 'nextCheck‐
886 point' either at the beginning of the path (i.e. zero), at the end of
887 the path, or at any intermediate file separator in the path. It will
888 never point to any other arbitrary position in the path. In the last of
889 the three valid cases, the implementation can assume that the path up
890 to and including the file separator is known and normalized.
891 typedef int Tcl_FSNormalizePathProc(
893 Tcl_Interp *interp,
894 Tcl_Obj *pathPtr,
895 int nextCheckpoint);
896
898 The fields in this section of the structure contain addresses of func‐
899 tions which are called to carry out the basic filesystem operations. A
900 filesystem which expects to be used with the complete standard Tcl com‐
901 mand set must implement all of these. If some of them are not imple‐
902 mented, then certain Tcl commands may fail when operating on paths
903 within that filesystem. However, in some instances this may be desir‐
904 able (for example, a read-only filesystem should not implement the last
905 four functions, and a filesystem which does not support symbolic links
906 need not implement the readlink function, etc. The Tcl core expects
907 filesystems to behave in this way).
908
910 Function to determine the type of a path in this filesystem. May be
911 NULL, in which case no type information will be available to users of
912 the filesystem. The 'type' is used only for informational purposes,
913 and should be returned as the string representation of the Tcl_Obj
914 which is returned. A typical return value might be "networked", "zip"
915 or "ftp". The Tcl_Obj result is owned by the filesystem and so Tcl
916 will increment the refCount of that object if it wishes to retain a
917 reference to it.
918 typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc(
920 Tcl_Obj *pathPtr);
921
923 Function to return the separator character(s) for this filesystem.
924 Must be implemented, otherwise the file separator command will not
925 function correctly. The usual return value will be a Tcl_Obj contain‐
926 ing the string "/".
927 typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
929 Tcl_Obj *pathPtr);
930
932 Function to process a Tcl_FSStat() call. Must be implemented for any
933 reasonable filesystem, since many Tcl level commands depend crucially
934 upon it (e.g. file atime, file isdirectory, file size, glob).
935 typedef int Tcl_FSStatProc(
937 Tcl_Obj *pathPtr,
938 Tcl_StatBuf *statPtr);
939 The Tcl_FSStatProc fills the stat structure statPtr with information
941 about the specified file. You do not need any access rights to the
942 file to get this information but you need search rights to all directo‐
943 ries named in the path leading to the file. The stat structure
944 includes info regarding device, inode (always 0 on Windows), privilege
945 mode, nlink (always 1 on Windows), user id (always 0 on Windows), group
946 id (always 0 on Windows), rdev (same as device on Windows), size, last
947 access time, last modification time, and creation time.
948 If the file represented by pathPtr exists, the Tcl_FSStatProc returns 0
950 and the stat structure is filled with data. Otherwise, -1 is returned,
951 and no stat info is given.
952
954 Function to process a Tcl_FSAccess() call. Must be implemented for any
955 reasonable filesystem, since many Tcl level commands depend crucially
956 upon it (e.g. file exists, file readable).
957 typedef int Tcl_FSAccessProc(
959 Tcl_Obj *pathPtr,
960 int mode);
961 The Tcl_FSAccessProc checks whether the process would be allowed to
963 read, write or test for existence of the file (or other file system
964 object) whose name is pathname. If pathname is a symbolic link, then
965 permissions of the file referred by this symbolic link should be
966 tested.
967 On success (all requested permissions granted), zero is returned. On
969 error (at least one bit in mode asked for a permission that is denied,
970 or some other error occurred), -1 is returned.
971
973 Function to process a Tcl_FSOpenFileChannel() call. Must be imple‐
974 mented for any reasonable filesystem, since any operations which
975 require open or accessing a file's contents will use it (e.g. open,
976 encoding, and many Tk commands).
977 typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
979 Tcl_Interp *interp,
980 Tcl_Obj *pathPtr,
981 int mode,
982 int permissions);
983 The Tcl_FSOpenFileChannelProc opens a file specified by pathPtr and
985 returns a channel handle that can be used to perform input and output
986 on the file. This API is modeled after the fopen procedure of the Unix
987 standard I/O library. The syntax and meaning of all arguments is simi‐
988 lar to those given in the Tcl open command when opening a file, where
989 the mode argument is a combination of the POSIX flags O_RDONLY,
990 O_WRONLY, etc. If an error occurs while opening the channel, the
991 Tcl_FSOpenFileChannelProc returns NULL and records a POSIX error code
992 that can be retrieved with Tcl_GetErrno. In addition, if interp is
993 non-NULL, the Tcl_FSOpenFileChannelProc leaves an error message in
994 interp's result after any error.
995 The newly created channel is not registered in the supplied inter‐
997 preter; to register it, use Tcl_RegisterChannel. If one of the standard
998 channels, stdin, stdout or stderr was previously closed, the act of
999 creating the new channel also assigns it as a replacement for the stan‐
1000 dard channel.
1001
1003 Function to process a Tcl_FSMatchInDirectory() call. If not imple‐
1004 mented, then glob and recursive copy functionality will be lacking in
1005 the filesystem (and this may impact commands like 'encoding names'
1006 which use glob functionality internally).
1007 typedef int Tcl_FSMatchInDirectoryProc(
1009 Tcl_Interp* interp,
1010 Tcl_Obj *result,
1011 Tcl_Obj *pathPtr,
1012 CONST char *pattern,
1013 Tcl_GlobTypeData * types);
1014 The function should return all files or directories (or other filesys‐
1016 tem objects) which match the given pattern and accord with the types
1017 specification given. There are two ways in which this function may be
1018 called. If pattern is NULL, then pathPtr is a full path specification
1019 of a single file or directory which should be checked for existence and
1020 correct type. Otherwise, pathPtr is a directory, the contents of which
1021 the function should search for files or directories which have the cor‐
1022 rect type. In either case, pathPtr can be assumed to be both non-NULL
1023 and non-empty. It is not currently documented whether pathPtr will
1024 have a file separator at its end of not, so code should be flexible to
1025 both possibilities.
1026 The return value is a standard Tcl result indicating whether an error
1028 occurred in the matching process. Error messages are placed in interp;
1029 on a TCL_OK result, results should be added to the result object given
1030 (which can be assumed to be a valid unshared Tcl list). The matches
1031 added to result should include any path prefix given in pathPtr (this
1032 usually means they will be absolute path specifications). Note that if
1033 no matches are found, that simply leads to an empty result; errors are
1034 only signaled for actual file or filesystem problems which may occur
1035 during the matching process.
1036 The Tcl_GlobTypeData structure passed in the types parameter contains
1038 the following fields:
1039 typedef struct Tcl_GlobTypeData {
1040 /* Corresponds to bcdpfls as in 'find -t' */
1041 int type;
1042 /* Corresponds to file permissions */
1043 int perm;
1044 /* Acceptable mac type */
1045 Tcl_Obj *macType;
1046 /* Acceptable mac creator */
1047 Tcl_Obj *macCreator;
1048 } Tcl_GlobTypeData;
1049 There are two specific cases which it is important to handle correctly,
1051 both when types is non-NULL. The two cases are when types->types &
1052 TCL_GLOB_TYPE_DIR or types->types & TCL_GLOB_TYPE_MOUNT are true (and
1053 in particular when the other flags are false). In the first of these
1054 cases, the function must list the contained directories. Tcl uses this
1055 to implement recursive globbing, so it is critical that filesystems
1056 implement directory matching correctly. In the second of these cases,
1057 with TCL_GLOB_TYPE_MOUNT, the filesystem must list the mount points
1058 which lie within the given pathPtr (and in this case, pathPtr need not
1059 lie within the same filesystem - different to all other cases in which
1060 this function is called). Support for this is critical if Tcl is to
1061 have seamless transitions between from one filesystem to another.
1062
1064 Function to process a Tcl_FSUtime() call. Required to allow setting
1065 (not reading) of times with 'file mtime', 'file atime' and the open-
1066 r/open-w/fcopy implementation of 'file copy'.
1067 typedef int Tcl_FSUtimeProc(
1069 Tcl_Obj *pathPtr,
1070 struct utimbuf *tval);
1071 The access and modification times of the file specified by pathPtr
1073 should be changed to the values given in the tval structure.
1074 The return value is a standard Tcl result indicating whether an error
1076 occurred in the process.
1077
1079 Function to process a Tcl_FSLink() call. Should be implemented only if
1080 the filesystem supports links, and may otherwise be NULL.
1081 typedef Tcl_Obj* Tcl_FSLinkProc(
1083 Tcl_Obj *linkNamePtr,
1084 Tcl_Obj *toPtr,
1085 int linkAction);
1086 If toPtr is NULL, the function is being asked to read the contents of a
1088 link. The result is a Tcl_Obj specifying the contents of the link
1089 given by linkNamePtr, or NULL if the link could not be read. The
1090 result is owned by the caller, which should call Tcl_DecrRefCount when
1091 the result is no longer needed. If toPtr is not NULL, the function
1092 should attempt to create a link. The result in this case should be
1093 toPtr if the link was successful and NULL otherwise. In this case the
1094 result is not owned by the caller. See the documentation for Tcl_FSLink
1095 for the correct interpretation of the linkAction flags.
1096
1098 Function to list any filesystem volumes added by this filesystem.
1099 Should be implemented only if the filesystem adds volumes at the head
1100 of the filesystem, so that they can be returned by 'file volumes'.
1101 typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
1103 The result should be a list of volumes added by this filesystem, or
1105 NULL (or an empty list) if no volumes are provided. The result object
1106 is considered to be owned by the filesystem (not by Tcl's core), but
1107 should be given a refCount for Tcl. Tcl will use the contents of the
1108 list and then decrement that refCount. This allows filesystems to
1109 choose whether they actually want to retain a 'master list' of volumes
1110 or not (if not, they generate the list on the fly and pass it to Tcl
1111 with a refCount of 1 and then forget about the list, if yes, then they
1112 simply increment the refCount of their master list and pass it to Tcl
1113 which will copy the contents and then decrement the count back to where
1114 it was).
1115 Therefore, Tcl considers return values from this proc to be read-only.
1117
1119 Function to list all attribute strings which are valid for this
1120 filesystem. If not implemented the filesystem will not support the
1121 file attributes command. This allows arbitrary additional information
1122 to be attached to files in the filesystem. If it is not implemented,
1123 there is no need to implement the get and set methods.
1124 typedef CONST char** Tcl_FSFileAttrStringsProc(
1126 Tcl_Obj *pathPtr,
1127 Tcl_Obj** objPtrRef);
1128 The called function may either return an array of strings, or may
1130 instead return NULL and place a Tcl list into the given objPtrRef. Tcl
1131 will take that list and first increment its refCount before using it.
1132 On completion of that use, Tcl will decrement its refCount. Hence if
1133 the list should be disposed of by Tcl when done, it should have a ref‐
1134 Count of zero, and if the list should not be disposed of, the filesys‐
1135 tem should ensure it retains a refCount on the object.
1136
1138 Function to process a Tcl_FSFileAttrsGet() call, used by 'file
1139 attributes'.
1140 typedef int Tcl_FSFileAttrsGetProc(
1142 Tcl_Interp *interp,
1143 int index,
1144 Tcl_Obj *pathPtr,
1145 Tcl_Obj **objPtrRef);
1146 Returns a standard Tcl return code. The attribute value retrieved,
1148 which corresponds to the index'th element in the list returned by the
1149 Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if TCL_OK
1150 was returned) and is likely to have a refCount of zero. Either way we
1151 must either store it somewhere (e.g. the Tcl result), or Incr/Decr its
1152 refCount to ensure it is properly freed.
1153
1155 Function to process a Tcl_FSFileAttrsSet() call, used by 'file
1156 attributes'. If the filesystem is read-only, there is no need to
1157 implement this.
1158 typedef int Tcl_FSFileAttrsSetProc(
1160 Tcl_Interp *interp,
1161 int index,
1162 Tcl_Obj *pathPtr,
1163 Tcl_Obj *objPtr);
1164 The attribute value of the index'th element in the list returned by the
1166 Tcl_FSFileAttrStringsProc should be set to the objPtr given.
1167
1169 Function to process a Tcl_FSCreateDirectory() call. Should be imple‐
1170 mented unless the FS is read-only.
1171 typedef int Tcl_FSCreateDirectoryProc(
1173 Tcl_Obj *pathPtr);
1174 The return value is a standard Tcl result indicating whether an error
1176 occurred in the process. If successful, a new directory should have
1177 been added to the filesystem in the location specified by pathPtr.
1178
1180 Function to process a 'Tcl_FSRemoveDirectory()' call. Should be imple‐
1181 mented unless the FS is read-only.
1182 typedef int Tcl_FSRemoveDirectoryProc(
1184 Tcl_Obj *pathPtr,
1185 int recursive,
1186 Tcl_Obj **errorPtr);
1187 The return value is a standard Tcl result indicating whether an error
1189 occurred in the process. If successful, the directory specified by
1190 pathPtr should have been removed from the filesystem. If the recursive
1191 flag is given, then a non-empty directory should be deleted without
1192 error. If an error does occur, the name of the file or directory which
1193 caused the error should be placed in errorPtr.
1194
1196 Function to process a Tcl_FSDeleteFile() call. Should be implemented
1197 unless the FS is read-only.
1198 typedef int Tcl_FSDeleteFileProc(
1200 Tcl_Obj *pathPtr);
1201 The return value is a standard Tcl result indicating whether an error
1203 occurred in the process. If successful, the file specified by pathPtr
1204 should have been removed from the filesystem. Note that, if the
1205 filesystem supports symbolic links, Tcl will always call this function
1206 and not Tcl_FSRemoveDirectoryProc when needed to delete them (even if
1207 they are symbolic links to directories).
1208
1211 Function to process a Tcl_FSLstat() call. If not implemented, Tcl will
1212 attempt to use the statProc defined above instead. Therefore it need
1213 only be implemented if a filesystem can differentiate between stat and
1214 lstat calls.
1215 typedef int Tcl_FSLstatProc(
1217 Tcl_Obj *pathPtr,
1218 Tcl_StatBuf *statPtr);
1219 The behavior of this function is very similar to that of the
1221 Tcl_FSStatProc defined above, except that if it is applied to a sym‐
1222 bolic link, it returns information about the link, not about the target
1223 file.
1224
1226 Function to process a Tcl_FSCopyFile() call. If not implemented Tcl
1227 will fall back on open-r, open-w and fcopy as a copying mechanism.
1228 Therefore it need only be implemented if the filesystem can perform
1229 that action more efficiently.
1230 typedef int Tcl_FSCopyFileProc(
1232 Tcl_Obj *srcPathPtr,
1233 Tcl_Obj *destPathPtr);
1234 The return value is a standard Tcl result indicating whether an error
1236 occurred in the copying process. Note that, destPathPtr is the name of
1237 the file which should become the copy of srcPathPtr. It is never the
1238 name of a directory into which srcPathPtr could be copied (i.e. the
1239 function is much simpler than the Tcl level 'file copy' subcommand).
1240 Note that, if the filesystem supports symbolic links, Tcl will always
1241 call this function and not Tcl_FSCopyDirectoryProc when needed to copy
1242 them (even if they are symbolic links to directories).
1243
1245 Function to process a Tcl_FSRenameFile() call. If not implemented, Tcl
1246 will fall back on a copy and delete mechanism. Therefore it need only
1247 be implemented if the filesystem can perform that action more effi‐
1248 ciently.
1249 typedef int Tcl_FSRenameFileProc(
1251 Tcl_Obj *srcPathPtr,
1252 Tcl_Obj *destPathPtr);
1253 The return value is a standard Tcl result indicating whether an error
1255 occurred in the renaming process.
1256
1258 Function to process a Tcl_FSCopyDirectory() call. If not implemented,
1259 Tcl will fall back on a recursive create-dir, file copy mechanism.
1260 Therefore it need only be implemented if the filesystem can perform
1261 that action more efficiently.
1262 typedef int Tcl_FSCopyDirectoryProc(
1264 Tcl_Obj *srcPathPtr,
1265 Tcl_Obj *destPathPtr,
1266 Tcl_Obj **errorPtr);
1267 The return value is a standard Tcl result indicating whether an error
1269 occurred in the copying process. If an error does occur, the name of
1270 the file or directory which caused the error should be placed in
1271 errorPtr. Note that, destPathPtr is the name of the directory-name
1272 which should become the mirror-image of srcPathPtr. It is not the name
1273 of a directory into which srcPathPtr should be copied (i.e. the func‐
1274 tion is much simpler than the Tcl level 'file copy' subcommand).
1275
1277 Function to process a Tcl_FSLoadFile() call. If not implemented, Tcl
1278 will fall back on a copy to native-temp followed by a Tcl_FSLoadFile on
1279 that temporary copy. Therefore it need only be implemented if the
1280 filesystem can load code directly, or it can be implemented simply to
1281 return TCL_ERROR to disable load functionality in this filesystem
1282 entirely.
1283 typedef int Tcl_FSLoadFileProc(
1285 Tcl_Interp * interp,
1286 Tcl_Obj *pathPtr,
1287 Tcl_LoadHandle * handlePtr,
1288 Tcl_FSUnloadFileProc * unloadProcPtr);
1289 Returns a standard Tcl completion code. If an error occurs, an error
1291 message is left in the interp's result. The function dynamically loads
1292 a binary code file into memory. On a successful load, the handlePtr
1293 should be filled with a token for the dynamically loaded file, and the
1294 unloadProcPtr should be filled in with the address of a procedure. The
1295 procedure will be called with the given Tcl_LoadHandle as its only
1296 parameter when Tcl needs to unload the file.
1297
1299 Function to unload a previously successfully loaded file. If load was
1300 implemented, then this should also be implemented, if there is any
1301 cleanup action required.
1302 typedef void Tcl_FSUnloadFileProc(
1304 Tcl_LoadHandle loadHandle);
1305
1307 Function to process a Tcl_FSGetCwd() call. Most filesystems need not
1308 implement this. It will usually only be called once, if 'getcwd' is
1309 called before 'chdir'. May be NULL.
1310 typedef Tcl_Obj* Tcl_FSGetCwdProc(
1312 Tcl_Interp *interp);
1313 If the filesystem supports a native notion of a current working direc‐
1315 tory (which might perhaps change independent of Tcl), this function
1316 should return that cwd as the result, or NULL if the current directory
1317 could not be determined (e.g. the user does not have appropriate per‐
1318 missions on the cwd directory). If NULL is returned, an error message
1319 is left in the interp's result.
1320
1322 Function to process a Tcl_FSChdir() call. If filesystems do not imple‐
1323 ment this, it will be emulated by a series of directory access checks.
1324 Otherwise, virtual filesystems which do implement it need only respond
1325 with a positive return result if the dirName is a valid, accessible
1326 directory in their filesystem. They need not remember the result,
1327 since that will be automatically remembered for use by GetCwd. Real
1328 filesystems should carry out the correct action (i.e. call the correct
1329 system 'chdir' api).
1330 typedef int Tcl_FSChdirProc(
1332 Tcl_Obj *pathPtr);
1333 The Tcl_FSChdirProc changes the applications current working directory
1335 to the value specified in pathPtr. The function returns -1 on error or
1336 0 on success.
1337
1339 stat access filesystem vfs
1340Tcl 8.4 Filesystem(3)