1 | '\" |
---|
2 | '\" Copyright (c) 2001 Vincent Darley |
---|
3 | '\" |
---|
4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
6 | '\" |
---|
7 | '\" RCS: @(#) $Id: FileSystem.3,v 1.62 2007/12/13 15:22:31 dgp Exp $ |
---|
8 | '\" |
---|
9 | .so man.macros |
---|
10 | .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures" |
---|
11 | .BS |
---|
12 | .SH NAME |
---|
13 | Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSEvalFileEx, Tcl_FSLoadFile, Tcl_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 |
---|
14 | .SH SYNOPSIS |
---|
15 | .nf |
---|
16 | \fB#include <tcl.h>\fR |
---|
17 | .sp |
---|
18 | int |
---|
19 | \fBTcl_FSRegister\fR(\fIclientData, fsPtr\fR) |
---|
20 | .sp |
---|
21 | int |
---|
22 | \fBTcl_FSUnregister\fR(\fIfsPtr\fR) |
---|
23 | .sp |
---|
24 | ClientData |
---|
25 | \fBTcl_FSData\fR(\fIfsPtr\fR) |
---|
26 | .sp |
---|
27 | void |
---|
28 | \fBTcl_FSMountsChanged\fR(\fIfsPtr\fR) |
---|
29 | .sp |
---|
30 | Tcl_Filesystem* |
---|
31 | \fBTcl_FSGetFileSystemForPath\fR(\fIpathPtr\fR) |
---|
32 | .sp |
---|
33 | Tcl_PathType |
---|
34 | \fBTcl_FSGetPathType\fR(\fIpathPtr\fR) |
---|
35 | .sp |
---|
36 | int |
---|
37 | \fBTcl_FSCopyFile\fR(\fIsrcPathPtr, destPathPtr\fR) |
---|
38 | .sp |
---|
39 | int |
---|
40 | \fBTcl_FSCopyDirectory\fR(\fIsrcPathPtr, destPathPtr, errorPtr\fR) |
---|
41 | .sp |
---|
42 | int |
---|
43 | \fBTcl_FSCreateDirectory\fR(\fIpathPtr\fR) |
---|
44 | .sp |
---|
45 | int |
---|
46 | \fBTcl_FSDeleteFile\fR(\fIpathPtr\fR) |
---|
47 | .sp |
---|
48 | int |
---|
49 | \fBTcl_FSRemoveDirectory\fR(\fIpathPtr, int recursive, errorPtr\fR) |
---|
50 | .sp |
---|
51 | int |
---|
52 | \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR) |
---|
53 | .sp |
---|
54 | Tcl_Obj* |
---|
55 | \fBTcl_FSListVolumes\fR(\fIvoid\fR) |
---|
56 | .sp |
---|
57 | .VS 8.5 |
---|
58 | int |
---|
59 | \fBTcl_FSEvalFileEx\fR(\fIinterp, pathPtr, encodingName\fR) |
---|
60 | .VE 8.5 |
---|
61 | .sp |
---|
62 | int |
---|
63 | \fBTcl_FSEvalFile\fR(\fIinterp, pathPtr\fR) |
---|
64 | .sp |
---|
65 | int |
---|
66 | \fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr, |
---|
67 | handlePtr, unloadProcPtr\fR) |
---|
68 | .sp |
---|
69 | int |
---|
70 | \fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR) |
---|
71 | .sp |
---|
72 | Tcl_Obj* |
---|
73 | \fBTcl_FSLink\fR(\fIlinkNamePtr, toPtr, linkAction\fR) |
---|
74 | .sp |
---|
75 | int |
---|
76 | \fBTcl_FSLstat\fR(\fIpathPtr, statPtr\fR) |
---|
77 | .sp |
---|
78 | int |
---|
79 | \fBTcl_FSUtime\fR(\fIpathPtr, tval\fR) |
---|
80 | .sp |
---|
81 | int |
---|
82 | \fBTcl_FSFileAttrsGet\fR(\fIinterp, int index, pathPtr, objPtrRef\fR) |
---|
83 | .sp |
---|
84 | int |
---|
85 | \fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR) |
---|
86 | .sp |
---|
87 | const char** |
---|
88 | \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR) |
---|
89 | .sp |
---|
90 | int |
---|
91 | \fBTcl_FSStat\fR(\fIpathPtr, statPtr\fR) |
---|
92 | .sp |
---|
93 | int |
---|
94 | \fBTcl_FSAccess\fR(\fIpathPtr, mode\fR) |
---|
95 | .sp |
---|
96 | Tcl_Channel |
---|
97 | \fBTcl_FSOpenFileChannel\fR(\fIinterp, pathPtr, modeString, permissions\fR) |
---|
98 | .sp |
---|
99 | Tcl_Obj* |
---|
100 | \fBTcl_FSGetCwd\fR(\fIinterp\fR) |
---|
101 | .sp |
---|
102 | int |
---|
103 | \fBTcl_FSChdir\fR(\fIpathPtr\fR) |
---|
104 | .sp |
---|
105 | Tcl_Obj* |
---|
106 | \fBTcl_FSPathSeparator\fR(\fIpathPtr\fR) |
---|
107 | .sp |
---|
108 | Tcl_Obj* |
---|
109 | \fBTcl_FSJoinPath\fR(\fIlistObj, elements\fR) |
---|
110 | .sp |
---|
111 | Tcl_Obj* |
---|
112 | \fBTcl_FSSplitPath\fR(\fIpathPtr, lenPtr\fR) |
---|
113 | .sp |
---|
114 | int |
---|
115 | \fBTcl_FSEqualPaths\fR(\fIfirstPtr, secondPtr\fR) |
---|
116 | .sp |
---|
117 | Tcl_Obj* |
---|
118 | \fBTcl_FSGetNormalizedPath\fR(\fIinterp, pathPtr\fR) |
---|
119 | .sp |
---|
120 | Tcl_Obj* |
---|
121 | \fBTcl_FSJoinToPath\fR(\fIbasePtr, objc, objv\fR) |
---|
122 | .sp |
---|
123 | int |
---|
124 | \fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR) |
---|
125 | .sp |
---|
126 | ClientData |
---|
127 | \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR) |
---|
128 | .sp |
---|
129 | Tcl_Obj * |
---|
130 | \fBTcl_FSGetTranslatedPath\fR(\fIinterp, pathPtr\fR) |
---|
131 | .sp |
---|
132 | const char * |
---|
133 | \fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR) |
---|
134 | .sp |
---|
135 | Tcl_Obj* |
---|
136 | \fBTcl_FSNewNativePath\fR(\fIfsPtr, clientData\fR) |
---|
137 | .sp |
---|
138 | const char * |
---|
139 | \fBTcl_FSGetNativePath\fR(\fIpathPtr\fR) |
---|
140 | .sp |
---|
141 | Tcl_Obj* |
---|
142 | \fBTcl_FSFileSystemInfo\fR(\fIpathPtr\fR) |
---|
143 | .sp |
---|
144 | Tcl_StatBuf* |
---|
145 | \fBTcl_AllocStatBuf\fR() |
---|
146 | .SH ARGUMENTS |
---|
147 | .AS Tcl_FSUnloadFileProc **unloadProcPtr out |
---|
148 | .AP Tcl_Filesystem *fsPtr in |
---|
149 | Points to a structure containing the addresses of procedures that |
---|
150 | can be called to perform the various filesystem operations. |
---|
151 | .AP Tcl_Obj *pathPtr in |
---|
152 | The path represented by this object is used for the operation in |
---|
153 | question. If the object does not already have an internal \fBpath\fR |
---|
154 | representation, it will be converted to have one. |
---|
155 | .AP Tcl_Obj *srcPathPtr in |
---|
156 | As for \fIpathPtr\fR, but used for the source file for a copy or |
---|
157 | rename operation. |
---|
158 | .AP Tcl_Obj *destPathPtr in |
---|
159 | As for \fIpathPtr\fR, but used for the destination filename for a copy or |
---|
160 | rename operation. |
---|
161 | .AP "const char" *encodingName in |
---|
162 | The encoding of the data stored in the |
---|
163 | file identified by \fIpathPtr\fR and to be evaluted. |
---|
164 | .AP "const char" *pattern in |
---|
165 | Only files or directories matching this pattern will be returned. |
---|
166 | .AP Tcl_GlobTypeData *types in |
---|
167 | Only files or directories matching the type descriptions contained in |
---|
168 | this structure will be returned. This parameter may be NULL. |
---|
169 | .AP Tcl_Interp *interp in |
---|
170 | Interpreter to use either for results, evaluation, or reporting error |
---|
171 | messages. |
---|
172 | .AP ClientData clientData in |
---|
173 | The native description of the path object to create. |
---|
174 | .AP Tcl_Obj *firstPtr in |
---|
175 | The first of two path objects to compare. The object may be converted |
---|
176 | to \fBpath\fR type. |
---|
177 | .AP Tcl_Obj *secondPtr in |
---|
178 | The second of two path objects to compare. The object may be converted |
---|
179 | to \fBpath\fR type. |
---|
180 | .AP Tcl_Obj *listObj in |
---|
181 | The list of path elements to operate on with a \fBjoin\fR operation. |
---|
182 | .AP int elements in |
---|
183 | If non-negative, the number of elements in the \fIlistObj\fR which should |
---|
184 | be joined together. If negative, then all elements are joined. |
---|
185 | .AP Tcl_Obj **errorPtr out |
---|
186 | In the case of an error, filled with an object containing the name of |
---|
187 | the file which caused an error in the various copy/rename operations. |
---|
188 | .AP Tcl_Obj **objPtrRef out |
---|
189 | Filled with an object containing the result of the operation. |
---|
190 | .AP Tcl_Obj *resultPtr out |
---|
191 | Pre-allocated object in which to store (using |
---|
192 | \fBTcl_ListObjAppendElement\fR) the list of |
---|
193 | files or directories which are successfully matched. |
---|
194 | .AP int mode in |
---|
195 | Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. R_OK, |
---|
196 | W_OK and X_OK request checking whether the file exists and has read, |
---|
197 | write and execute permissions, respectively. F_OK just requests |
---|
198 | checking for the existence of the file. |
---|
199 | .AP Tcl_StatBuf *statPtr out |
---|
200 | The structure that contains the result of a stat or lstat operation. |
---|
201 | .AP "const char" *sym1 in |
---|
202 | Name of a procedure to look up in the file's symbol table |
---|
203 | .AP "const char" *sym2 in |
---|
204 | Name of a procedure to look up in the file's symbol table |
---|
205 | .AP Tcl_PackageInitProc **proc1Ptr out |
---|
206 | Filled with the init function for this code. |
---|
207 | .AP Tcl_PackageInitProc **proc2Ptr out |
---|
208 | Filled with the safe-init function for this code. |
---|
209 | .AP ClientData *clientDataPtr out |
---|
210 | Filled with the clientData value to pass to this code's unload |
---|
211 | function when it is called. |
---|
212 | .AP Tcl_LoadHandle *handlePtr out |
---|
213 | Filled with an abstract token representing the loaded file. |
---|
214 | .AP Tcl_FSUnloadFileProc **unloadProcPtr out |
---|
215 | Filled with the function to use to unload this piece of code. |
---|
216 | .AP utimbuf *tval in |
---|
217 | The access and modification times in this structure are read and |
---|
218 | used to set those values for a given file. |
---|
219 | .AP "const char" *modeString in |
---|
220 | Specifies how the file is to be accessed. May have any of the values |
---|
221 | allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. |
---|
222 | .AP int permissions in |
---|
223 | POSIX-style permission flags such as 0644. If a new file is created, these |
---|
224 | permissions will be set on the created file. |
---|
225 | .AP int *lenPtr out |
---|
226 | If non-NULL, filled with the number of elements in the split path. |
---|
227 | .AP Tcl_Obj *basePtr in |
---|
228 | The base path on to which to join the given elements. May be NULL. |
---|
229 | .AP int objc in |
---|
230 | The number of elements in \fIobjv\fR. |
---|
231 | .AP "Tcl_Obj *const" objv[] in |
---|
232 | The elements to join to the given base path. |
---|
233 | .AP Tcl_Obj *linkNamePtr in |
---|
234 | The name of the link to be created or read. |
---|
235 | .AP Tcl_Obj *toPtr in |
---|
236 | What the link called \fIlinkNamePtr\fR should be linked to, or NULL if |
---|
237 | the symbolic link specified by \fIlinkNamePtr\fR is to be read. |
---|
238 | .AP int linkAction in |
---|
239 | OR-ed combination of flags indicating what kind of link should be |
---|
240 | created (will be ignored if \fItoPtr\fR is NULL). Valid bits to set |
---|
241 | are \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR. |
---|
242 | When both flags are set and the underlying filesystem can do either, |
---|
243 | symbolic links are preferred. |
---|
244 | .BE |
---|
245 | |
---|
246 | .SH DESCRIPTION |
---|
247 | .PP |
---|
248 | There are several reasons for calling the \fBTcl_FS\fR API functions |
---|
249 | (e.g. \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR) |
---|
250 | rather than calling system level functions like \fBaccess\fR and |
---|
251 | \fBstat\fR directly. First, they will work cross-platform, so an |
---|
252 | extension which calls them should work unmodified on Unix and |
---|
253 | Windows. Second, the Windows implementation of some of these functions |
---|
254 | fixes some bugs in the system level calls. Third, these function calls |
---|
255 | deal with any |
---|
256 | .QW "Utf to platform-native" |
---|
257 | path conversions which may be |
---|
258 | required (and may cache the results of such conversions for greater |
---|
259 | efficiency on subsequent calls). Fourth, and perhaps most importantly, |
---|
260 | all of these functions are |
---|
261 | .QW "virtual filesystem aware" . |
---|
262 | Any virtual filesystem (VFS for short) which has been registered (through |
---|
263 | \fBTcl_FSRegister\fR) may reroute file access to alternative |
---|
264 | media or access methods. This means that all of these functions (and |
---|
265 | therefore the corresponding \fBfile\fR, \fBglob\fR, \fBpwd\fR, \fBcd\fR, |
---|
266 | \fBopen\fR, etc. Tcl commands) may be operate on |
---|
267 | .QW files |
---|
268 | which are not |
---|
269 | native files in the native filesystem. This also means that any Tcl |
---|
270 | extension which accesses the filesystem (FS for short) through this API is |
---|
271 | automatically |
---|
272 | .QW "virtual filesystem aware" . |
---|
273 | Of course, if an extension |
---|
274 | accesses the native filesystem directly (through platform-specific |
---|
275 | APIs, for example), then Tcl cannot intercept such calls. |
---|
276 | .PP |
---|
277 | If appropriate VFSes have been registered, the |
---|
278 | .QW files |
---|
279 | may, to give two |
---|
280 | examples, be remote (e.g. situated on a remote ftp server) or archived |
---|
281 | (e.g. lying inside a .zip archive). Such registered filesystems provide |
---|
282 | a lookup table of functions to implement all or some of the functionality |
---|
283 | listed here. Finally, the \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR calls |
---|
284 | abstract away from what the |
---|
285 | .QW "struct stat" |
---|
286 | buffer is actually |
---|
287 | declared to be, allowing the same code to be used both on systems with |
---|
288 | and systems without support for files larger than 2GB in size. |
---|
289 | .PP |
---|
290 | The \fBTcl_FS\fR API is objectified and may cache internal |
---|
291 | representations and other path-related strings (e.g. the current working |
---|
292 | directory). One side-effect of this is that one must not pass in objects |
---|
293 | with a reference count of zero to any of these functions. If such calls were |
---|
294 | handled, they might result |
---|
295 | in memory leaks (under some circumstances, the filesystem code may wish |
---|
296 | to retain a reference to the passed in object, and so one must not assume |
---|
297 | that after any of these calls return, the object still has a reference count of |
---|
298 | zero - it may have been incremented) or in a direct segmentation fault |
---|
299 | (or other memory access error) |
---|
300 | due to the object being freed part way through the complex object |
---|
301 | manipulation required to ensure that the path is fully normalized and |
---|
302 | absolute for filesystem determination. The practical lesson to learn |
---|
303 | from this is that |
---|
304 | .CS |
---|
305 | Tcl_Obj *path = Tcl_NewStringObj(...); |
---|
306 | Tcl_FS\fIWhatever\fR(path); |
---|
307 | Tcl_DecrRefCount(path); |
---|
308 | .CE |
---|
309 | is wrong, and may cause memory errors. The \fIpath\fR must have its |
---|
310 | reference count incremented before passing it in, or |
---|
311 | decrementing it. For this reason, objects with a reference count of zero are |
---|
312 | considered not to be valid filesystem paths and calling any Tcl_FS API |
---|
313 | function with such an object will result in no action being taken. |
---|
314 | .SS "FS API FUNCTIONS" |
---|
315 | \fBTcl_FSCopyFile\fR attempts to copy the file given by \fIsrcPathPtr\fR to the |
---|
316 | path name given by \fIdestPathPtr\fR. If the two paths given lie in the same |
---|
317 | filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that |
---|
318 | filesystem's |
---|
319 | .QW "copy file" |
---|
320 | function is called (if it is non-NULL). |
---|
321 | Otherwise the function returns -1 and sets the \fBerrno\fR global C |
---|
322 | variable to the |
---|
323 | .QW EXDEV |
---|
324 | POSIX error code (which signifies a |
---|
325 | .QW "cross-domain link" ). |
---|
326 | .PP |
---|
327 | \fBTcl_FSCopyDirectory\fR attempts to copy the directory given by \fIsrcPathPtr\fR to the |
---|
328 | path name given by \fIdestPathPtr\fR. If the two paths given lie in the same |
---|
329 | filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that |
---|
330 | filesystem's |
---|
331 | .QW "copy file" |
---|
332 | function is called (if it is non-NULL). |
---|
333 | Otherwise the function returns -1 and sets the \fBerrno\fR global C |
---|
334 | variable to the |
---|
335 | .QW EXDEV |
---|
336 | POSIX error code (which signifies a |
---|
337 | .QW "cross-domain link" ). |
---|
338 | .PP |
---|
339 | \fBTcl_FSCreateDirectory\fR attempts to create the directory given by |
---|
340 | \fIpathPtr\fR by calling the owning filesystem's |
---|
341 | .QW "create directory" |
---|
342 | function. |
---|
343 | .PP |
---|
344 | \fBTcl_FSDeleteFile\fR attempts to delete the file given by |
---|
345 | \fIpathPtr\fR by calling the owning filesystem's |
---|
346 | .QW "delete file" |
---|
347 | function. |
---|
348 | .PP |
---|
349 | \fBTcl_FSRemoveDirectory\fR attempts to remove the directory given by |
---|
350 | \fIpathPtr\fR by calling the owning filesystem's |
---|
351 | .QW "remove directory" |
---|
352 | function. |
---|
353 | .PP |
---|
354 | \fBTcl_FSRenameFile\fR attempts to rename the file or directory given by |
---|
355 | \fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths |
---|
356 | given lie in the same filesystem (according to |
---|
357 | \fBTcl_FSGetFileSystemForPath\fR) then that filesystem's |
---|
358 | .QW "rename file" |
---|
359 | function is called (if it is non-NULL). Otherwise the function returns -1 |
---|
360 | and sets the \fBerrno\fR global C variable to the |
---|
361 | .QW EXDEV |
---|
362 | POSIX error code (which signifies a |
---|
363 | .QW "cross-domain link" ). |
---|
364 | .PP |
---|
365 | \fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL |
---|
366 | .QW "list volumes" |
---|
367 | function and asks them to return their list of root volumes. It |
---|
368 | accumulates the return values in a list which is returned to the |
---|
369 | caller (with a reference count of 0). |
---|
370 | .PP |
---|
371 | .VS 8.5 |
---|
372 | \fBTcl_FSEvalFileEx\fR reads the file given by \fIpathPtr\fR using |
---|
373 | the encoding identified by \fIencodingName\fR and evaluates |
---|
374 | its contents as a Tcl script. It returns the same information as |
---|
375 | \fBTcl_EvalObjEx\fR. |
---|
376 | If \fIencodingName\fR is NULL, the system encoding is used for |
---|
377 | reading the file contents. |
---|
378 | If the file could not be read then a Tcl error is returned to describe |
---|
379 | why the file could not be read. |
---|
380 | The eofchar for files is |
---|
381 | .QW \e32 |
---|
382 | (^Z) for all platforms. |
---|
383 | If you require a |
---|
384 | .QW ^Z |
---|
385 | in code for string comparison, you can use |
---|
386 | .QW \e032 |
---|
387 | or |
---|
388 | .QW \eu001a , |
---|
389 | which will be safely substituted by the Tcl interpreter into |
---|
390 | .QW ^Z . |
---|
391 | \fBTcl_FSEvalFile\fR is a simpler version of |
---|
392 | \fBTcl_FSEvalFileEx\fR that always uses the system encoding |
---|
393 | when reading the file. |
---|
394 | .VE 8.5 |
---|
395 | .PP |
---|
396 | \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and |
---|
397 | returns the addresses of two procedures within that file, if they are |
---|
398 | defined. The appropriate function for the filesystem to which \fIpathPtr\fR |
---|
399 | belongs will be called. If that filesystem does not implement this |
---|
400 | function (most virtual filesystems will not, because of OS limitations |
---|
401 | in dynamically loading binary code), Tcl will attempt to copy the file |
---|
402 | to a temporary directory and load that temporary file. |
---|
403 | .PP |
---|
404 | Returns a standard Tcl completion code. If an error occurs, an error |
---|
405 | message is left in the \fIinterp\fR's result. |
---|
406 | .PP |
---|
407 | \fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a |
---|
408 | directory for all files which match a given pattern. The appropriate |
---|
409 | function for the filesystem to which \fIpathPtr\fR belongs will be called. |
---|
410 | .PP |
---|
411 | The return value is a standard Tcl result indicating whether an error |
---|
412 | occurred in globbing. Error messages are placed in interp (unless |
---|
413 | interp is NULL, which is allowed), but good results are placed in the |
---|
414 | resultPtr given. |
---|
415 | .PP |
---|
416 | Note that the \fBglob\fR code implements recursive patterns internally, so |
---|
417 | this function will only ever be passed simple patterns, which can be |
---|
418 | matched using the logic of \fBstring match\fR. To handle recursion, Tcl |
---|
419 | will call this function frequently asking only for directories to be |
---|
420 | returned. A special case of being called with a NULL pattern indicates |
---|
421 | that the path needs to be checked only for the correct type. |
---|
422 | .PP |
---|
423 | \fBTcl_FSLink\fR replaces the library version of \fBreadlink\fR, and |
---|
424 | extends it to support the creation of links. The appropriate function |
---|
425 | for the filesystem to which \fIlinkNamePtr\fR belongs will be called. |
---|
426 | .PP |
---|
427 | If the \fItoPtr\fR is NULL, a |
---|
428 | .QW "read link" |
---|
429 | action is performed. The result |
---|
430 | is a Tcl_Obj specifying the contents of the symbolic link given by |
---|
431 | \fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned |
---|
432 | by the caller, which should call Tcl_DecrRefCount when the result is no |
---|
433 | longer needed. If the \fItoPtr\fR is not NULL, Tcl should create a link |
---|
434 | of one of the types passed in in the \fIlinkAction\fR flag. This flag is |
---|
435 | an ORed combination of \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR. |
---|
436 | Where a choice exists (i.e. more than one flag is passed in), the Tcl |
---|
437 | convention is to prefer symbolic links. When a link is successfully |
---|
438 | created, the return value should be \fItoPtr\fR (which is therefore |
---|
439 | already owned by the caller). If unsuccessful, NULL is returned. |
---|
440 | .PP |
---|
441 | \fBTcl_FSLstat\fR fills the stat structure \fIstatPtr\fR with information |
---|
442 | about the specified file. You do not need any access rights to the |
---|
443 | file to get this information but you need search rights to all |
---|
444 | directories named in the path leading to the file. The stat structure |
---|
445 | includes info regarding device, inode (always 0 on Windows), |
---|
446 | privilege mode, nlink (always 1 on Windows), user id (always 0 on |
---|
447 | Windows), group id (always 0 on Windows), rdev (same as device on |
---|
448 | Windows), size, last access time, last modification time, and creation |
---|
449 | time. |
---|
450 | .PP |
---|
451 | If \fIpath\fR exists, \fBTcl_FSLstat\fR returns 0 and the stat structure |
---|
452 | is filled with data. Otherwise, -1 is returned, and no stat info is |
---|
453 | given. |
---|
454 | .PP |
---|
455 | \fBTcl_FSUtime\fR replaces the library version of utime. |
---|
456 | .PP |
---|
457 | This returns 0 on success and -1 on error (as per the \fButime\fR |
---|
458 | documentation). If successful, the function |
---|
459 | will update the |
---|
460 | .QW atime |
---|
461 | and |
---|
462 | .QW mtime |
---|
463 | values of the file given. |
---|
464 | .PP |
---|
465 | \fBTcl_FSFileAttrsGet\fR implements read access for the hookable \fBfile |
---|
466 | attributes\fR subcommand. The appropriate function for the filesystem to |
---|
467 | which \fIpathPtr\fR belongs will be called. |
---|
468 | .PP |
---|
469 | If the result is \fBTCL_OK\fR, then an object was placed in |
---|
470 | \fIobjPtrRef\fR, which |
---|
471 | will only be temporarily valid (unless \fBTcl_IncrRefCount\fR is called). |
---|
472 | .PP |
---|
473 | \fBTcl_FSFileAttrsSet\fR implements write access for the hookable \fBfile |
---|
474 | attributes\fR subcommand. The appropriate function for the filesystem to |
---|
475 | which \fIpathPtr\fR belongs will be called. |
---|
476 | .PP |
---|
477 | \fBTcl_FSFileAttrStrings\fR implements part of the hookable \fBfile |
---|
478 | attributes\fR subcommand. The appropriate function for the filesystem |
---|
479 | to which \fIpathPtr\fR belongs will be called. |
---|
480 | .PP |
---|
481 | The called procedure may either return an array of strings, or may |
---|
482 | instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR. Tcl |
---|
483 | will take that list and first increment its reference count before using it. |
---|
484 | On completion of that use, Tcl will decrement its reference count. Hence if |
---|
485 | the list should be disposed of by Tcl when done, it should have a |
---|
486 | reference count of zero, and if the list should not be disposed of, the |
---|
487 | filesystem should ensure it retains a reference count to the object. |
---|
488 | .PP |
---|
489 | \fBTcl_FSAccess\fR checks whether the process would be allowed to read, |
---|
490 | write or test for existence of the file (or other filesystem object) |
---|
491 | whose name is \fIpathname\fR. If \fIpathname\fR is a symbolic link on Unix, |
---|
492 | then permissions of the file referred by this symbolic link are |
---|
493 | tested. |
---|
494 | .PP |
---|
495 | On success (all requested permissions granted), zero is returned. On |
---|
496 | error (at least one bit in mode asked for a permission that is denied, |
---|
497 | or some other error occurred), -1 is returned. |
---|
498 | .PP |
---|
499 | \fBTcl_FSStat\fR fills the stat structure \fIstatPtr\fR with information |
---|
500 | about the specified file. You do not need any access rights to the |
---|
501 | file to get this information but you need search rights to all |
---|
502 | directories named in the path leading to the file. The stat structure |
---|
503 | includes info regarding device, inode (always 0 on Windows), |
---|
504 | privilege mode, nlink (always 1 on Windows), user id (always 0 on |
---|
505 | Windows), group id (always 0 on Windows), rdev (same as device on |
---|
506 | Windows), size, last access time, last modification time, and creation |
---|
507 | time. |
---|
508 | .PP |
---|
509 | If \fIpath\fR exists, \fBTcl_FSStat\fR returns 0 and the stat structure |
---|
510 | is filled with data. Otherwise, -1 is returned, and no stat info is |
---|
511 | given. |
---|
512 | .PP |
---|
513 | \fBTcl_FSOpenFileChannel\fR opens a file specified by \fIpathPtr\fR and |
---|
514 | returns a channel handle that can be used to perform input and output on |
---|
515 | the file. This API is modeled after the \fBfopen\fR procedure of |
---|
516 | the Unix standard I/O library. |
---|
517 | The syntax and meaning of all arguments is similar to those |
---|
518 | given in the Tcl \fBopen\fR command when opening a file. |
---|
519 | If an error occurs while opening the channel, \fBTcl_FSOpenFileChannel\fR |
---|
520 | returns NULL and records a POSIX error code that can be |
---|
521 | retrieved with \fBTcl_GetErrno\fR. |
---|
522 | In addition, if \fIinterp\fR is non-NULL, \fBTcl_FSOpenFileChannel\fR |
---|
523 | leaves an error message in \fIinterp\fR's result after any error. |
---|
524 | .PP |
---|
525 | The newly created channel is not registered in the supplied interpreter; to |
---|
526 | register it, use \fBTcl_RegisterChannel\fR, described below. |
---|
527 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
---|
528 | previously closed, the act of creating the new channel also assigns it as a |
---|
529 | replacement for the standard channel. |
---|
530 | .PP |
---|
531 | \fBTcl_FSGetCwd\fR replaces the library version of \fBgetcwd\fR. |
---|
532 | .PP |
---|
533 | It returns the Tcl library's current working directory. This may be |
---|
534 | different to the native platform's working directory, which happens when |
---|
535 | the current working directory is not in the native filesystem. |
---|
536 | .PP |
---|
537 | The result is a pointer to a Tcl_Obj specifying the current directory, |
---|
538 | or NULL if the current directory could not be determined. If NULL is |
---|
539 | returned, an error message is left in the \fIinterp\fR's result. |
---|
540 | .PP |
---|
541 | The result already has its reference count incremented for the caller. When |
---|
542 | it is no longer needed, that reference count should be decremented. This is |
---|
543 | needed for thread-safety purposes, to allow multiple threads to access |
---|
544 | this and related functions, while ensuring the results are always |
---|
545 | valid. |
---|
546 | .PP |
---|
547 | \fBTcl_FSChdir\fR replaces the library version of \fBchdir\fR. The path is |
---|
548 | normalized and then passed to the filesystem which claims it. If that |
---|
549 | filesystem does not implement this function, Tcl will fallback to a |
---|
550 | combination of \fBstat\fR and \fBaccess\fR to check whether the directory |
---|
551 | exists and has appropriate permissions. |
---|
552 | .PP |
---|
553 | For results, see \fBchdir\fR documentation. If successful, we keep a |
---|
554 | record of the successful path in \fIcwdPathPtr\fR for subsequent calls to |
---|
555 | \fBTcl_FSGetCwd\fR. |
---|
556 | .PP |
---|
557 | \fBTcl_FSPathSeparator\fR returns the separator character to be used for |
---|
558 | most specific element of the path specified by \fIpathPtr\fR (i.e. the last |
---|
559 | part of the path). |
---|
560 | .PP |
---|
561 | The separator is returned as a Tcl_Obj containing a string of length |
---|
562 | 1. If the path is invalid, NULL is returned. |
---|
563 | .PP |
---|
564 | \fBTcl_FSJoinPath\fR takes the given Tcl_Obj, which must be a valid |
---|
565 | list (which is allowed to have a reference count of zero), and returns the path |
---|
566 | object given by considering the first \fIelements\fR elements as valid path |
---|
567 | segments (each path segment may be a complete path, a partial path or |
---|
568 | just a single possible directory or file name). If any path segment is |
---|
569 | actually an absolute path, then all prior path segments are discarded. |
---|
570 | If \fIelements\fR is less than 0, we use the entire list. |
---|
571 | .PP |
---|
572 | It is possible that the returned object is actually an element |
---|
573 | of the given list, so the caller should be careful to increment the |
---|
574 | reference count of the result before freeing the list. |
---|
575 | .PP |
---|
576 | The returned object, typically with a reference count of zero (but it |
---|
577 | could be shared |
---|
578 | under some conditions), contains the joined path. The caller must |
---|
579 | add a reference count to the object before using it. In particular, the |
---|
580 | returned object could be an element of the given list, so freeing the |
---|
581 | list might free the object prematurely if no reference count has been taken. |
---|
582 | If the number of elements is zero, then the returned object will be |
---|
583 | an empty-string Tcl_Obj. |
---|
584 | .PP |
---|
585 | \fBTcl_FSSplitPath\fR takes the given Tcl_Obj, which should be a valid path, |
---|
586 | and returns a Tcl list object containing each segment of that path as |
---|
587 | an element. |
---|
588 | It returns a list object with a reference count of zero. If the |
---|
589 | passed in \fIlenPtr\fR is non-NULL, the variable it points to will be |
---|
590 | updated to contain the number of elements in the returned list. |
---|
591 | .PP |
---|
592 | \fBTcl_FSEqualPaths\fR tests whether the two paths given represent the same |
---|
593 | filesystem object |
---|
594 | .PP |
---|
595 | It returns 1 if the paths are equal, and 0 if they are different. If |
---|
596 | either path is NULL, 0 is always returned. |
---|
597 | .PP |
---|
598 | \fBTcl_FSGetNormalizedPath\fR this important function attempts to extract |
---|
599 | from the given Tcl_Obj a unique normalized path representation, whose |
---|
600 | string value can be used as a unique identifier for the file. |
---|
601 | .PP |
---|
602 | It returns the normalized path object, owned by Tcl, or NULL if the path |
---|
603 | was invalid or could otherwise not be successfully converted. |
---|
604 | Extraction of absolute, normalized paths is very efficient (because the |
---|
605 | filesystem operates on these representations internally), although the |
---|
606 | result when the filesystem contains numerous symbolic links may not be |
---|
607 | the most user-friendly version of a path. The return value is owned by |
---|
608 | Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR passed in |
---|
609 | (unless that is a relative path, in which case the normalized path |
---|
610 | object may be freed any time the cwd changes) - the caller can of |
---|
611 | course increment the refCount if it wishes to maintain a copy for longer. |
---|
612 | .PP |
---|
613 | \fBTcl_FSJoinToPath\fR takes the given object, which should usually be a |
---|
614 | valid path or NULL, and joins onto it the array of paths segments |
---|
615 | given. |
---|
616 | .PP |
---|
617 | Returns object, typically with refCount of zero (but it could be shared |
---|
618 | under some conditions), containing the joined path. The caller must |
---|
619 | add a refCount to the object before using it. If any of the objects |
---|
620 | passed into this function (pathPtr or path elements) have a refCount |
---|
621 | of zero, they will be freed when this function returns. |
---|
622 | .PP |
---|
623 | \fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid |
---|
624 | Tcl path type, taking account of the fact that the cwd may have changed |
---|
625 | even if this object is already supposedly of the correct type. |
---|
626 | The filename may begin with |
---|
627 | .QW ~ |
---|
628 | (to indicate current user's home directory) or |
---|
629 | .QW ~<user> |
---|
630 | (to indicate any user's home directory). |
---|
631 | .PP |
---|
632 | If the conversion succeeds (i.e. the object is a valid path in one of |
---|
633 | the current filesystems), then \fBTCL_OK\fR is returned. Otherwise |
---|
634 | \fBTCL_ERROR\fR is returned, and an error message may |
---|
635 | be left in the interpreter. |
---|
636 | .PP |
---|
637 | \fBTcl_FSGetInternalRep\fR extracts the internal representation of a given |
---|
638 | path object, in the given filesystem. If the path object belongs to a |
---|
639 | different filesystem, we return NULL. If the internal representation is |
---|
640 | currently NULL, we attempt to generate it, by calling the filesystem's |
---|
641 | \fBTcl_FSCreateInternalRepProc\fR. |
---|
642 | .PP |
---|
643 | Returns NULL or a valid internal path representation. This internal |
---|
644 | representation is cached, so that repeated calls to this function will |
---|
645 | not require additional conversions. |
---|
646 | .PP |
---|
647 | \fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path |
---|
648 | from the given Tcl_Obj. |
---|
649 | .PP |
---|
650 | If the translation succeeds (i.e. the object is a valid path), then it is |
---|
651 | returned. Otherwise NULL will be returned, and an error message may be |
---|
652 | left in the interpreter. A |
---|
653 | .QW translated |
---|
654 | path is one which contains no |
---|
655 | .QW ~ |
---|
656 | or |
---|
657 | .QW ~user |
---|
658 | sequences (these have been expanded to their current |
---|
659 | representation in the filesystem). The object returned is owned by the |
---|
660 | caller, which must store it or call Tcl_DecrRefCount to ensure memory is |
---|
661 | freed. This function is of little practical use, and |
---|
662 | \fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually |
---|
663 | better functions to use for most purposes. |
---|
664 | .PP |
---|
665 | \fBTcl_FSGetTranslatedStringPath\fR does the same as |
---|
666 | \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL. |
---|
667 | The string returned is dynamically allocated and owned by the caller, |
---|
668 | which must store it or call \fBckfree\fR to ensure it is freed. Again, |
---|
669 | \fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually |
---|
670 | better functions to use for most purposes. |
---|
671 | .PP |
---|
672 | \fBTcl_FSNewNativePath\fR performs something like the reverse of the |
---|
673 | usual obj->path->nativerep conversions. If some code retrieves a path |
---|
674 | in native form (from, e.g. \fBreadlink\fR or a native dialog), and that path |
---|
675 | is to be used at the Tcl level, then calling this function is an |
---|
676 | efficient way of creating the appropriate path object type. |
---|
677 | .PP |
---|
678 | The resulting object is a pure |
---|
679 | .QW path |
---|
680 | object, which will only receive |
---|
681 | a UTF-8 string representation if that is required by some Tcl code. |
---|
682 | .PP |
---|
683 | \fBTcl_FSGetNativePath\fR is for use by the Win/Unix native |
---|
684 | filesystems, so that they can easily retrieve the native (char* or |
---|
685 | TCHAR*) representation of a path. This function is a convenience |
---|
686 | wrapper around \fBTcl_FSGetInternalRep\fR, and assumes the native |
---|
687 | representation is string-based. It may be desirable in the future to |
---|
688 | have non-string-based native representations (for example, on MacOSX, a |
---|
689 | representation using a fileSpec of FSRef structure would probably be |
---|
690 | more efficient). On Windows a full Unicode representation would allow |
---|
691 | for paths of unlimited length. Currently the representation is simply a |
---|
692 | character string which may contain either the relative path or a |
---|
693 | complete, absolute normalized path in the native encoding (complex |
---|
694 | conditions dictate which of these will be provided, so neither can be |
---|
695 | relied upon, unless the path is known to be absolute). If you need a |
---|
696 | native path which must be absolute, then you should ask for the native |
---|
697 | version of a normalized path. If for some reason a non-absolute, |
---|
698 | non-normalized version of the path is needed, that must be constructed |
---|
699 | separately (e.g. using \fBTcl_FSGetTranslatedPath\fR). |
---|
700 | .PP |
---|
701 | The native representation is cached so that repeated calls to this |
---|
702 | function will not require additional conversions. The return value is |
---|
703 | owned by Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR |
---|
704 | passed in (unless that is a relative path, in which case the native |
---|
705 | representation may be freed any time the cwd changes). |
---|
706 | .PP |
---|
707 | \fBTcl_FSFileSystemInfo\fR returns a list of two elements. The first |
---|
708 | element is the name of the filesystem (e.g. |
---|
709 | .QW native , |
---|
710 | .QW vfs , |
---|
711 | .QW zip , |
---|
712 | or |
---|
713 | .QW prowrap , |
---|
714 | perhaps), and the second is the particular type of the |
---|
715 | given path within that filesystem (which is filesystem dependent). The |
---|
716 | second element may be empty if the filesystem does not provide a |
---|
717 | further categorization of files. |
---|
718 | .PP |
---|
719 | A valid list object is returned, unless the path object is not |
---|
720 | recognized, when NULL will be returned. |
---|
721 | .PP |
---|
722 | \fBTcl_FSGetFileSystemForPath\fR returns the a pointer to the |
---|
723 | \fBTcl_Filesystem\fR which accepts this path as valid. |
---|
724 | .PP |
---|
725 | If no filesystem will accept the path, NULL is returned. |
---|
726 | .PP |
---|
727 | \fBTcl_FSGetPathType\fR determines whether the given path is relative |
---|
728 | to the current directory, relative to the current volume, or |
---|
729 | absolute. |
---|
730 | .PP |
---|
731 | It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or |
---|
732 | \fBTCL_PATH_VOLUME_RELATIVE\fR |
---|
733 | .PP |
---|
734 | \fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system |
---|
735 | heap (which may be deallocated by being passed to \fBckfree\fR.) This |
---|
736 | allows extensions to invoke \fBTcl_FSStat\fR and \fBTcl_FSLStat\fR |
---|
737 | without being dependent on the size of the buffer. That in turn |
---|
738 | depends on the flags used to build Tcl. |
---|
739 | .SH "THE VIRTUAL FILESYSTEM API" |
---|
740 | .PP |
---|
741 | A filesystem provides a \fBTcl_Filesystem\fR structure that contains |
---|
742 | pointers to functions that implement the various operations on a |
---|
743 | filesystem; these operations are invoked as needed by the generic |
---|
744 | layer, which generally occurs through the functions listed above. |
---|
745 | .PP |
---|
746 | The \fBTcl_Filesystem\fR structures are manipulated using the following |
---|
747 | methods. |
---|
748 | .PP |
---|
749 | \fBTcl_FSRegister\fR takes a pointer to a filesystem structure and an |
---|
750 | optional piece of data to associated with that filesystem. On calling |
---|
751 | this function, Tcl will attach the filesystem to the list of known |
---|
752 | filesystems, and it will become fully functional immediately. Tcl does |
---|
753 | not check if the same filesystem is registered multiple times (and in |
---|
754 | general that is not a good thing to do). \fBTCL_OK\fR will be returned. |
---|
755 | .PP |
---|
756 | \fBTcl_FSUnregister\fR removes the given filesystem structure from |
---|
757 | the list of known filesystems, if it is known, and returns \fBTCL_OK\fR. If |
---|
758 | the filesystem is not currently registered, \fBTCL_ERROR\fR is returned. |
---|
759 | .PP |
---|
760 | \fBTcl_FSData\fR will return the ClientData associated with the given |
---|
761 | filesystem, if that filesystem is registered. Otherwise it will |
---|
762 | return NULL. |
---|
763 | .PP |
---|
764 | \fBTcl_FSMountsChanged\fR is used to inform the Tcl's core that |
---|
765 | the set of mount points for the given (already registered) filesystem |
---|
766 | have changed, and that cached file representations may therefore no |
---|
767 | longer be correct. |
---|
768 | .SS "THE TCL_FILESYSTEM STRUCTURE" |
---|
769 | .PP |
---|
770 | The \fBTcl_Filesystem\fR structure contains the following fields: |
---|
771 | .CS |
---|
772 | typedef struct Tcl_Filesystem { |
---|
773 | const char *\fItypeName\fR; |
---|
774 | int \fIstructureLength\fR; |
---|
775 | Tcl_FSVersion \fIversion\fR; |
---|
776 | Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR; |
---|
777 | Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR; |
---|
778 | Tcl_FSFreeInternalRepProc *\fIfreeInternalRepProc\fR; |
---|
779 | Tcl_FSInternalToNormalizedProc *\fIinternalToNormalizedProc\fR; |
---|
780 | Tcl_FSCreateInternalRepProc *\fIcreateInternalRepProc\fR; |
---|
781 | Tcl_FSNormalizePathProc *\fInormalizePathProc\fR; |
---|
782 | Tcl_FSFilesystemPathTypeProc *\fIfilesystemPathTypeProc\fR; |
---|
783 | Tcl_FSFilesystemSeparatorProc *\fIfilesystemSeparatorProc\fR; |
---|
784 | Tcl_FSStatProc *\fIstatProc\fR; |
---|
785 | Tcl_FSAccessProc *\fIaccessProc\fR; |
---|
786 | Tcl_FSOpenFileChannelProc *\fIopenFileChannelProc\fR; |
---|
787 | Tcl_FSMatchInDirectoryProc *\fImatchInDirectoryProc\fR; |
---|
788 | Tcl_FSUtimeProc *\fIutimeProc\fR; |
---|
789 | Tcl_FSLinkProc *\fIlinkProc\fR; |
---|
790 | Tcl_FSListVolumesProc *\fIlistVolumesProc\fR; |
---|
791 | Tcl_FSFileAttrStringsProc *\fIfileAttrStringsProc\fR; |
---|
792 | Tcl_FSFileAttrsGetProc *\fIfileAttrsGetProc\fR; |
---|
793 | Tcl_FSFileAttrsSetProc *\fIfileAttrsSetProc\fR; |
---|
794 | Tcl_FSCreateDirectoryProc *\fIcreateDirectoryProc\fR; |
---|
795 | Tcl_FSRemoveDirectoryProc *\fIremoveDirectoryProc\fR; |
---|
796 | Tcl_FSDeleteFileProc *\fIdeleteFileProc\fR; |
---|
797 | Tcl_FSCopyFileProc *\fIcopyFileProc\fR; |
---|
798 | Tcl_FSRenameFileProc *\fIrenameFileProc\fR; |
---|
799 | Tcl_FSCopyDirectoryProc *\fIcopyDirectoryProc\fR; |
---|
800 | Tcl_FSLstatProc *\fIlstatProc\fR; |
---|
801 | Tcl_FSLoadFileProc *\fIloadFileProc\fR; |
---|
802 | Tcl_FSGetCwdProc *\fIgetCwdProc\fR; |
---|
803 | Tcl_FSChdirProc *\fIchdirProc\fR; |
---|
804 | } Tcl_Filesystem; |
---|
805 | .CE |
---|
806 | .PP |
---|
807 | Except for the first three fields in this structure which contain |
---|
808 | simple data elements, all entries contain addresses of functions called |
---|
809 | by the generic filesystem layer to perform the complete range of |
---|
810 | filesystem related actions. |
---|
811 | .PP |
---|
812 | The many functions in this structure are broken down into three |
---|
813 | categories: infrastructure functions (almost all of which must be |
---|
814 | implemented), operational functions (which must be implemented if a |
---|
815 | complete filesystem is provided), and efficiency functions (which need |
---|
816 | only be implemented if they can be done so efficiently, or if they have |
---|
817 | side-effects which are required by the filesystem; Tcl has less |
---|
818 | efficient emulations it can fall back on). It is important to note |
---|
819 | that, in the current version of Tcl, most of these fallbacks are only |
---|
820 | used to handle commands initiated in Tcl, not in C. What this means is, |
---|
821 | that if a \fBfile rename\fR command is issued in Tcl, and the relevant |
---|
822 | filesystem(s) do not implement their \fITcl_FSRenameFileProc\fR, Tcl's |
---|
823 | core will instead fallback on a combination of other filesystem |
---|
824 | functions (it will use \fITcl_FSCopyFileProc\fR followed by |
---|
825 | \fITcl_FSDeleteFileProc\fR, and if \fITcl_FSCopyFileProc\fR is not |
---|
826 | implemented there is a further fallback). However, if a |
---|
827 | \fITcl_FSRenameFileProc\fR command is issued at the C level, no such |
---|
828 | fallbacks occur. This is true except for the last four entries in the |
---|
829 | filesystem table (\fBlstat\fR, \fBload\fR, \fBgetcwd\fR and \fBchdir\fR) |
---|
830 | for which fallbacks do in fact occur at the C level. |
---|
831 | .PP |
---|
832 | Any functions which take path names in Tcl_Obj form take |
---|
833 | those names in UTF\-8 form. The filesystem infrastructure API is |
---|
834 | designed to support efficient, cached conversion of these UTF\-8 paths |
---|
835 | to other native representations. |
---|
836 | .SS "EXAMPLE FILESYSTEM DEFINITION" |
---|
837 | .PP |
---|
838 | Here is the filesystem lookup table used by the |
---|
839 | .QW vfs |
---|
840 | extension which allows filesystem actions to be implemented in Tcl. |
---|
841 | .CS |
---|
842 | static Tcl_Filesystem vfsFilesystem = { |
---|
843 | "tclvfs", |
---|
844 | sizeof(Tcl_Filesystem), |
---|
845 | TCL_FILESYSTEM_VERSION_1, |
---|
846 | &VfsPathInFilesystem, |
---|
847 | &VfsDupInternalRep, |
---|
848 | &VfsFreeInternalRep, |
---|
849 | /* No internal to normalized, since we don't create |
---|
850 | * any pure 'internal' Tcl_Obj path representations */ |
---|
851 | NULL, |
---|
852 | /* No create native rep function, since we don't use |
---|
853 | * it and don't choose to support uses of |
---|
854 | * Tcl_FSNewNativePath */ |
---|
855 | NULL, |
---|
856 | /* Normalize path isn't needed - we assume paths only |
---|
857 | * have one representation */ |
---|
858 | NULL, |
---|
859 | &VfsFilesystemPathType, |
---|
860 | &VfsFilesystemSeparator, |
---|
861 | &VfsStat, |
---|
862 | &VfsAccess, |
---|
863 | &VfsOpenFileChannel, |
---|
864 | &VfsMatchInDirectory, |
---|
865 | &VfsUtime, |
---|
866 | /* We choose not to support symbolic links inside our |
---|
867 | * VFS's */ |
---|
868 | NULL, |
---|
869 | &VfsListVolumes, |
---|
870 | &VfsFileAttrStrings, |
---|
871 | &VfsFileAttrsGet, |
---|
872 | &VfsFileAttrsSet, |
---|
873 | &VfsCreateDirectory, |
---|
874 | &VfsRemoveDirectory, |
---|
875 | &VfsDeleteFile, |
---|
876 | /* No copy file; use the core fallback mechanism */ |
---|
877 | NULL, |
---|
878 | /* No rename file; use the core fallback mechanism */ |
---|
879 | NULL, |
---|
880 | /* No copy directory; use the core fallback mechanism */ |
---|
881 | NULL, |
---|
882 | /* Core will use stat for lstat */ |
---|
883 | NULL, |
---|
884 | /* No load; use the core fallback mechansism */ |
---|
885 | NULL, |
---|
886 | /* We don't need a getcwd or chdir; the core's own |
---|
887 | * internal value is suitable */ |
---|
888 | NULL, |
---|
889 | NULL |
---|
890 | }; |
---|
891 | .CE |
---|
892 | .SH "FILESYSTEM INFRASTRUCTURE" |
---|
893 | .PP |
---|
894 | These fields contain basic information about the filesystem structure |
---|
895 | and addresses of functions which are used to associate |
---|
896 | a particular filesystem with a file path, and deal with the internal |
---|
897 | handling of path representations, for example copying and freeing such |
---|
898 | representations. |
---|
899 | .SS TYPENAME |
---|
900 | .PP |
---|
901 | The \fItypeName\fR field contains a null-terminated string that |
---|
902 | identifies the type of the filesystem implemented, e.g. |
---|
903 | .QW native , |
---|
904 | .QW zip |
---|
905 | or |
---|
906 | .QW vfs . |
---|
907 | .SS "STRUCTURE LENGTH" |
---|
908 | .PP |
---|
909 | The \fIstructureLength\fR field is generally implemented as |
---|
910 | \fIsizeof(Tcl_Filesystem)\fR, and is there to allow easier |
---|
911 | binary backwards compatibility if the size of the structure |
---|
912 | changes in a future Tcl release. |
---|
913 | .SS VERSION |
---|
914 | .PP |
---|
915 | The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR. |
---|
916 | .SS PATHINFILESYSTEMPROC |
---|
917 | .PP |
---|
918 | The \fIpathInFilesystemProc\fR field contains the address of a function |
---|
919 | which is called to determine whether a given path object belongs to this |
---|
920 | filesystem or not. Tcl will only call the rest of the filesystem |
---|
921 | functions with a path for which this function has returned \fBTCL_OK\fR. |
---|
922 | If the path does not belong, -1 should be returned (the behaviour of Tcl |
---|
923 | for any other return value is not defined). If \fBTCL_OK\fR is returned, |
---|
924 | then the optional \fIclientDataPtr\fR output parameter can be used to |
---|
925 | return an internal (filesystem specific) representation of the path, |
---|
926 | which will be cached inside the path object, and may be retrieved |
---|
927 | efficiently by the other filesystem functions. Tcl will simultaneously |
---|
928 | cache the fact that this path belongs to this filesystem. Such caches |
---|
929 | are invalidated when filesystem structures are added or removed from |
---|
930 | Tcl's internal list of known filesystems. |
---|
931 | .PP |
---|
932 | .CS |
---|
933 | typedef int Tcl_FSPathInFilesystemProc( |
---|
934 | Tcl_Obj *\fIpathPtr\fR, |
---|
935 | ClientData *\fIclientDataPtr\fR); |
---|
936 | .CE |
---|
937 | .SS DUPINTERNALREPPROC |
---|
938 | .PP |
---|
939 | This function makes a copy of a path's internal representation, and is |
---|
940 | called when Tcl needs to duplicate a path object. If NULL, Tcl will |
---|
941 | simply not copy the internal representation, which may then need to be |
---|
942 | regenerated later. |
---|
943 | .PP |
---|
944 | .CS |
---|
945 | typedef ClientData Tcl_FSDupInternalRepProc( |
---|
946 | ClientData \fIclientData\fR); |
---|
947 | .CE |
---|
948 | .SS FREEINTERNALREPPROC |
---|
949 | Free the internal representation. This must be implemented if internal |
---|
950 | representations need freeing (i.e. if some memory is allocated when an |
---|
951 | internal representation is generated), but may otherwise be NULL. |
---|
952 | .PP |
---|
953 | .CS |
---|
954 | typedef void Tcl_FSFreeInternalRepProc( |
---|
955 | ClientData \fIclientData\fR); |
---|
956 | .CE |
---|
957 | .SS INTERNALTONORMALIZEDPROC |
---|
958 | .PP |
---|
959 | Function to convert internal representation to a normalized path. Only |
---|
960 | required if the filesystem creates pure path objects with no string/path |
---|
961 | representation. The return value is a Tcl object whose string |
---|
962 | representation is the normalized path. |
---|
963 | .PP |
---|
964 | .CS |
---|
965 | typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc( |
---|
966 | ClientData \fIclientData\fR); |
---|
967 | .CE |
---|
968 | .SS CREATEINTERNALREPPROC |
---|
969 | .PP |
---|
970 | Function to take a path object, and calculate an internal |
---|
971 | representation for it, and store that native representation in the |
---|
972 | object. May be NULL if paths have no internal representation, or if |
---|
973 | the \fITcl_FSPathInFilesystemProc\fR for this filesystem always |
---|
974 | immediately creates an internal representation for paths it accepts. |
---|
975 | .PP |
---|
976 | .CS |
---|
977 | typedef ClientData Tcl_FSCreateInternalRepProc( |
---|
978 | Tcl_Obj *\fIpathPtr\fR); |
---|
979 | .CE |
---|
980 | .SS NORMALIZEPATHPROC |
---|
981 | .PP |
---|
982 | Function to normalize a path. Should be implemented for all |
---|
983 | filesystems which can have multiple string representations for the same |
---|
984 | path object. In Tcl, every |
---|
985 | .QW path |
---|
986 | must have a single unique |
---|
987 | .QW normalized |
---|
988 | string representation. Depending on the filesystem, |
---|
989 | there may be more than one unnormalized string representation which |
---|
990 | refers to that path (e.g. a relative path, a path with different |
---|
991 | character case if the filesystem is case insensitive, a path contain a |
---|
992 | reference to a home directory such as |
---|
993 | .QW ~ , |
---|
994 | a path containing symbolic |
---|
995 | links, etc). If the very last component in the path is a symbolic |
---|
996 | link, it should not be converted into the object it points to (but |
---|
997 | its case or other aspects should be made unique). All other path |
---|
998 | components should be converted from symbolic links. This one |
---|
999 | exception is required to agree with Tcl's semantics with \fBfile |
---|
1000 | delete\fR, \fBfile rename\fR, \fBfile copy\fR operating on symbolic links. |
---|
1001 | This function may be called with \fInextCheckpoint\fR either |
---|
1002 | at the beginning of the path (i.e. zero), at the end of the path, or |
---|
1003 | at any intermediate file separator in the path. It will never |
---|
1004 | point to any other arbitrary position in the path. In the last of |
---|
1005 | the three valid cases, the implementation can assume that the path |
---|
1006 | up to and including the file separator is known and normalized. |
---|
1007 | .PP |
---|
1008 | .CS |
---|
1009 | typedef int Tcl_FSNormalizePathProc( |
---|
1010 | Tcl_Interp *\fIinterp\fR, |
---|
1011 | Tcl_Obj *\fIpathPtr\fR, |
---|
1012 | int \fInextCheckpoint\fR); |
---|
1013 | .CE |
---|
1014 | .SH "FILESYSTEM OPERATIONS" |
---|
1015 | .PP |
---|
1016 | The fields in this section of the structure contain addresses of |
---|
1017 | functions which are called to carry out the basic filesystem |
---|
1018 | operations. A filesystem which expects to be used with the complete |
---|
1019 | standard Tcl command set must implement all of these. If some of |
---|
1020 | them are not implemented, then certain Tcl commands may fail when |
---|
1021 | operating on paths within that filesystem. However, in some instances |
---|
1022 | this may be desirable (for example, a read-only filesystem should not |
---|
1023 | implement the last four functions, and a filesystem which does not |
---|
1024 | support symbolic links need not implement the \fBreadlink\fR function, |
---|
1025 | etc. The Tcl core expects filesystems to behave in this way). |
---|
1026 | .SS FILESYSTEMPATHTYPEPROC |
---|
1027 | .PP |
---|
1028 | Function to determine the type of a path in this filesystem. May be |
---|
1029 | NULL, in which case no type information will be available to users of |
---|
1030 | the filesystem. The |
---|
1031 | .QW type |
---|
1032 | is used only for informational purposes, |
---|
1033 | and should be returned as the string representation of the Tcl_Obj |
---|
1034 | which is returned. A typical return value might be |
---|
1035 | .QW networked , |
---|
1036 | .QW zip |
---|
1037 | or |
---|
1038 | .QW ftp . |
---|
1039 | The Tcl_Obj result is owned by the filesystem and so Tcl will |
---|
1040 | increment the refCount of that object if it wishes to retain a reference |
---|
1041 | to it. |
---|
1042 | .PP |
---|
1043 | .CS |
---|
1044 | typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc( |
---|
1045 | Tcl_Obj *\fIpathPtr\fR); |
---|
1046 | .CE |
---|
1047 | .SS FILESYSTEMSEPARATORPROC |
---|
1048 | .PP |
---|
1049 | Function to return the separator character(s) for this filesystem. |
---|
1050 | This need only be implemented if the filesystem wishes to use a |
---|
1051 | different separator than the standard string |
---|
1052 | .QW / . |
---|
1053 | Amongst other |
---|
1054 | uses, it is returned by the \fBfile separator\fR command. The |
---|
1055 | return value should be an object with refCount of zero. |
---|
1056 | .PP |
---|
1057 | .CS |
---|
1058 | typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc( |
---|
1059 | Tcl_Obj *\fIpathPtr\fR); |
---|
1060 | .CE |
---|
1061 | .SS STATPROC |
---|
1062 | .PP |
---|
1063 | Function to process a \fBTcl_FSStat\fR call. Must be implemented for any |
---|
1064 | reasonable filesystem, since many Tcl level commands depend crucially |
---|
1065 | upon it (e.g. \fBfile atime\fR, \fBfile isdirectory\fR, \fBfile size\fR, |
---|
1066 | \fBglob\fR). |
---|
1067 | .PP |
---|
1068 | .CS |
---|
1069 | typedef int Tcl_FSStatProc( |
---|
1070 | Tcl_Obj *\fIpathPtr\fR, |
---|
1071 | Tcl_StatBuf *\fIstatPtr\fR); |
---|
1072 | .CE |
---|
1073 | .PP |
---|
1074 | The \fBTcl_FSStatProc\fR fills the stat structure \fIstatPtr\fR with |
---|
1075 | information about the specified file. You do not need any access |
---|
1076 | rights to the file to get this information but you need search rights |
---|
1077 | to all directories named in the path leading to the file. The stat |
---|
1078 | structure includes info regarding device, inode (always 0 on Windows), |
---|
1079 | privilege mode, nlink (always 1 on Windows), user id (always 0 on |
---|
1080 | Windows), group id (always 0 on Windows), rdev (same as device on |
---|
1081 | Windows), size, last access time, last modification time, and creation |
---|
1082 | time. |
---|
1083 | .PP |
---|
1084 | If the file represented by \fIpathPtr\fR exists, the |
---|
1085 | \fBTcl_FSStatProc\fR returns 0 and the stat structure is filled with |
---|
1086 | data. Otherwise, -1 is returned, and no stat info is given. |
---|
1087 | .SS ACCESSPROC |
---|
1088 | .PP |
---|
1089 | Function to process a \fBTcl_FSAccess\fR call. Must be implemented for |
---|
1090 | any reasonable filesystem, since many Tcl level commands depend crucially |
---|
1091 | upon it (e.g. \fBfile exists\fR, \fBfile readable\fR). |
---|
1092 | .PP |
---|
1093 | .CS |
---|
1094 | typedef int Tcl_FSAccessProc( |
---|
1095 | Tcl_Obj *\fIpathPtr\fR, |
---|
1096 | int \fImode\fR); |
---|
1097 | .CE |
---|
1098 | .PP |
---|
1099 | The \fBTcl_FSAccessProc\fR checks whether the process would be allowed |
---|
1100 | to read, write or test for existence of the file (or other filesystem |
---|
1101 | object) whose name is in \fIpathPtr\fR. If the pathname refers to a |
---|
1102 | symbolic link, then the |
---|
1103 | permissions of the file referred by this symbolic link should be tested. |
---|
1104 | .PP |
---|
1105 | On success (all requested permissions granted), zero is returned. On |
---|
1106 | error (at least one bit in mode asked for a permission that is denied, |
---|
1107 | or some other error occurred), -1 is returned. |
---|
1108 | .SS OPENFILECHANNELPROC |
---|
1109 | .PP |
---|
1110 | Function to process a \fBTcl_FSOpenFileChannel\fR call. Must be |
---|
1111 | implemented for any reasonable filesystem, since any operations |
---|
1112 | which require open or accessing a file's contents will use it |
---|
1113 | (e.g. \fBopen\fR, \fBencoding\fR, and many Tk commands). |
---|
1114 | .PP |
---|
1115 | .CS |
---|
1116 | typedef Tcl_Channel Tcl_FSOpenFileChannelProc( |
---|
1117 | Tcl_Interp *\fIinterp\fR, |
---|
1118 | Tcl_Obj *\fIpathPtr\fR, |
---|
1119 | int \fImode\fR, |
---|
1120 | int \fIpermissions\fR); |
---|
1121 | .CE |
---|
1122 | .PP |
---|
1123 | The \fBTcl_FSOpenFileChannelProc\fR opens a file specified by |
---|
1124 | \fIpathPtr\fR and returns a channel handle that can be used to perform |
---|
1125 | input and output on the file. This API is modeled after the \fBfopen\fR |
---|
1126 | procedure of the Unix standard I/O library. The syntax and meaning of |
---|
1127 | all arguments is similar to those given in the Tcl \fBopen\fR command |
---|
1128 | when opening a file, where the \fImode\fR argument is a combination of |
---|
1129 | the POSIX flags O_RDONLY, O_WRONLY, etc. If an error occurs while |
---|
1130 | opening the channel, the \fBTcl_FSOpenFileChannelProc\fR returns NULL and |
---|
1131 | records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. |
---|
1132 | In addition, if \fIinterp\fR is non-NULL, the |
---|
1133 | \fBTcl_FSOpenFileChannelProc\fR leaves an error message in \fIinterp\fR's |
---|
1134 | result after any error. |
---|
1135 | .PP |
---|
1136 | The newly created channel is not registered in the supplied |
---|
1137 | interpreter; to register it, use \fBTcl_RegisterChannel\fR. If one of |
---|
1138 | the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
---|
1139 | previously closed, the act of creating the new channel also assigns it |
---|
1140 | as a replacement for the standard channel. |
---|
1141 | .SS MATCHINDIRECTORYPROC |
---|
1142 | .PP |
---|
1143 | Function to process a \fBTcl_FSMatchInDirectory\fR call. If not |
---|
1144 | implemented, then glob and recursive copy functionality will be lacking |
---|
1145 | in the filesystem (and this may impact commands like \fBencoding names\fR |
---|
1146 | which use glob functionality internally). |
---|
1147 | .PP |
---|
1148 | .CS |
---|
1149 | typedef int Tcl_FSMatchInDirectoryProc( |
---|
1150 | Tcl_Interp* \fIinterp\fR, |
---|
1151 | Tcl_Obj *\fIresultPtr\fR, |
---|
1152 | Tcl_Obj *\fIpathPtr\fR, |
---|
1153 | const char *\fIpattern\fR, |
---|
1154 | Tcl_GlobTypeData *\fItypes\fR); |
---|
1155 | .CE |
---|
1156 | .PP |
---|
1157 | The function should return all files or directories (or other filesystem |
---|
1158 | objects) which match the given pattern and accord with the \fItypes\fR |
---|
1159 | specification given. There are two ways in which this function may be |
---|
1160 | called. If \fIpattern\fR is NULL, then \fIpathPtr\fR is a full path |
---|
1161 | specification of a single file or directory which should be checked for |
---|
1162 | existence and correct type. Otherwise, \fIpathPtr\fR is a directory, the |
---|
1163 | contents of which the function should search for files or directories |
---|
1164 | which have the correct type. In either case, \fIpathPtr\fR can be |
---|
1165 | assumed to be both non-NULL and non-empty. It is not currently |
---|
1166 | documented whether \fIpathPtr\fR will have a file separator at its end of |
---|
1167 | not, so code should be flexible to both possibilities. |
---|
1168 | .PP |
---|
1169 | The return value is a standard Tcl result indicating whether an error |
---|
1170 | occurred in the matching process. Error messages are placed in |
---|
1171 | \fIinterp\fR, unless \fIinterp\fR in NULL in which case no error |
---|
1172 | message need be generated; on a \fBTCL_OK\fR result, results should be |
---|
1173 | added to the \fIresultPtr\fR object given (which can be assumed to be a |
---|
1174 | valid unshared Tcl list). The matches added |
---|
1175 | to \fIresultPtr\fR should include any path prefix given in \fIpathPtr\fR |
---|
1176 | (this usually means they will be absolute path specifications). |
---|
1177 | Note that if no matches are found, that simply leads to an empty |
---|
1178 | result; errors are only signaled for actual file or filesystem |
---|
1179 | problems which may occur during the matching process. |
---|
1180 | .PP |
---|
1181 | The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR |
---|
1182 | parameter contains the following fields: |
---|
1183 | .CS |
---|
1184 | typedef struct Tcl_GlobTypeData { |
---|
1185 | /* Corresponds to bcdpfls as in 'find -t' */ |
---|
1186 | int \fItype\fR; |
---|
1187 | /* Corresponds to file permissions */ |
---|
1188 | int \fIperm\fR; |
---|
1189 | /* Acceptable mac type */ |
---|
1190 | Tcl_Obj *\fImacType\fR; |
---|
1191 | /* Acceptable mac creator */ |
---|
1192 | Tcl_Obj *\fImacCreator\fR; |
---|
1193 | } Tcl_GlobTypeData; |
---|
1194 | .CE |
---|
1195 | .PP |
---|
1196 | There are two specific cases which it is important to handle correctly, |
---|
1197 | both when \fItypes\fR is non-NULL. The two cases are when \fItypes->types |
---|
1198 | & TCL_GLOB_TYPE_DIR\fR or \fItypes->types & TCL_GLOB_TYPE_MOUNT\fR are |
---|
1199 | true (and in particular when the other flags are false). In the first of |
---|
1200 | these cases, the function must list the contained directories. Tcl uses |
---|
1201 | this to implement recursive globbing, so it is critical that filesystems |
---|
1202 | implement directory matching correctly. In the second of these cases, |
---|
1203 | with \fBTCL_GLOB_TYPE_MOUNT\fR, the filesystem must list the mount points |
---|
1204 | which lie within the given \fIpathPtr\fR (and in this case, \fIpathPtr\fR |
---|
1205 | need not lie within the same filesystem - different to all other cases in |
---|
1206 | which this function is called). Support for this is critical if Tcl is |
---|
1207 | to have seamless transitions between from one filesystem to another. |
---|
1208 | .SS UTIMEPROC |
---|
1209 | .PP |
---|
1210 | Function to process a \fBTcl_FSUtime\fR call. Required to allow setting |
---|
1211 | (not reading) of times with \fBfile mtime\fR, \fBfile atime\fR and the |
---|
1212 | open-r/open-w/fcopy implementation of \fBfile copy\fR. |
---|
1213 | .PP |
---|
1214 | .CS |
---|
1215 | typedef int Tcl_FSUtimeProc( |
---|
1216 | Tcl_Obj *\fIpathPtr\fR, |
---|
1217 | struct utimbuf *\fItval\fR); |
---|
1218 | .CE |
---|
1219 | .PP |
---|
1220 | The access and modification times of the file specified by \fIpathPtr\fR |
---|
1221 | should be changed to the values given in the \fItval\fR structure. |
---|
1222 | .PP |
---|
1223 | The return value should be 0 on success and -1 on an error, as |
---|
1224 | with the system \fButime\fR. |
---|
1225 | .SS LINKPROC |
---|
1226 | .PP |
---|
1227 | Function to process a \fBTcl_FSLink\fR call. Should be implemented |
---|
1228 | only if the filesystem supports links, and may otherwise be NULL. |
---|
1229 | .PP |
---|
1230 | .CS |
---|
1231 | typedef Tcl_Obj* Tcl_FSLinkProc( |
---|
1232 | Tcl_Obj *\fIlinkNamePtr\fR, |
---|
1233 | Tcl_Obj *\fItoPtr\fR, |
---|
1234 | int \fIlinkAction\fR); |
---|
1235 | .CE |
---|
1236 | .PP |
---|
1237 | If \fItoPtr\fR is NULL, the function is being asked to read the |
---|
1238 | contents of a link. The result is a Tcl_Obj specifying the contents of |
---|
1239 | the link given by \fIlinkNamePtr\fR, or NULL if the link could |
---|
1240 | not be read. The result is owned by the caller (and should therefore |
---|
1241 | have its ref count incremented before being returned). Any callers |
---|
1242 | should call Tcl_DecrRefCount on this result when it is no longer needed. |
---|
1243 | If \fItoPtr\fR is not NULL, the function should attempt to create a link. |
---|
1244 | The result in this case should be \fItoPtr\fR if the link was successful |
---|
1245 | and NULL otherwise. In this case the result is not owned by the caller |
---|
1246 | (i.e. no ref count manipulation on either end is needed). See |
---|
1247 | the documentation for \fBTcl_FSLink\fR for the correct interpretation |
---|
1248 | of the \fIlinkAction\fR flags. |
---|
1249 | .SS LISTVOLUMESPROC |
---|
1250 | .PP |
---|
1251 | Function to list any filesystem volumes added by this filesystem. |
---|
1252 | Should be implemented only if the filesystem adds volumes at the head |
---|
1253 | of the filesystem, so that they can be returned by \fBfile volumes\fR. |
---|
1254 | .PP |
---|
1255 | .CS |
---|
1256 | typedef Tcl_Obj* Tcl_FSListVolumesProc(void); |
---|
1257 | .CE |
---|
1258 | .PP |
---|
1259 | The result should be a list of volumes added by this filesystem, or |
---|
1260 | NULL (or an empty list) if no volumes are provided. The result object |
---|
1261 | is considered to be owned by the filesystem (not by Tcl's core), but |
---|
1262 | should be given a refCount for Tcl. Tcl will use the contents of the |
---|
1263 | list and then decrement that refCount. This allows filesystems to |
---|
1264 | choose whether they actually want to retain a |
---|
1265 | .QW "master list" |
---|
1266 | of volumes |
---|
1267 | or not (if not, they generate the list on the fly and pass it to Tcl |
---|
1268 | with a refCount of 1 and then forget about the list, if yes, then |
---|
1269 | they simply increment the refCount of their master list and pass it |
---|
1270 | to Tcl which will copy the contents and then decrement the count back |
---|
1271 | to where it was). |
---|
1272 | .PP |
---|
1273 | Therefore, Tcl considers return values from this proc to be read-only. |
---|
1274 | .SS FILEATTRSTRINGSPROC |
---|
1275 | .PP |
---|
1276 | Function to list all attribute strings which are valid for this |
---|
1277 | filesystem. If not implemented the filesystem will not support |
---|
1278 | the \fBfile attributes\fR command. This allows arbitrary additional |
---|
1279 | information to be attached to files in the filesystem. If it is |
---|
1280 | not implemented, there is no need to implement the \fBget\fR and \fBset\fR |
---|
1281 | methods. |
---|
1282 | .PP |
---|
1283 | .CS |
---|
1284 | typedef const char** Tcl_FSFileAttrStringsProc( |
---|
1285 | Tcl_Obj *\fIpathPtr\fR, |
---|
1286 | Tcl_Obj** \fIobjPtrRef\fR); |
---|
1287 | .CE |
---|
1288 | .PP |
---|
1289 | The called function may either return an array of strings, or may |
---|
1290 | instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR. Tcl |
---|
1291 | will take that list and first increment its reference count before using it. |
---|
1292 | On completion of that use, Tcl will decrement its reference count. Hence if |
---|
1293 | the list should be disposed of by Tcl when done, it should have a |
---|
1294 | reference count of zero, and if the list should not be disposed of, the |
---|
1295 | filesystem should ensure it returns an object with a refererence count |
---|
1296 | of at least one. |
---|
1297 | .SS FILEATTRSGETPROC |
---|
1298 | .PP |
---|
1299 | Function to process a \fBTcl_FSFileAttrsGet\fR call, used by \fBfile |
---|
1300 | attributes\fR. |
---|
1301 | .PP |
---|
1302 | .CS |
---|
1303 | typedef int Tcl_FSFileAttrsGetProc( |
---|
1304 | Tcl_Interp *\fIinterp\fR, |
---|
1305 | int \fIindex\fR, |
---|
1306 | Tcl_Obj *\fIpathPtr\fR, |
---|
1307 | Tcl_Obj **\fIobjPtrRef\fR); |
---|
1308 | .CE |
---|
1309 | .PP |
---|
1310 | Returns a standard Tcl return code. The attribute value retrieved, |
---|
1311 | which corresponds to the \fIindex\fR'th element in the list returned by |
---|
1312 | the \fBTcl_FSFileAttrStringsProc\fR, is a Tcl_Obj placed in \fIobjPtrRef\fR (if |
---|
1313 | \fBTCL_OK\fR was returned) and is likely to have a reference count of zero. Either |
---|
1314 | way we must either store it somewhere (e.g. the Tcl result), or |
---|
1315 | Incr/Decr its reference count to ensure it is properly freed. |
---|
1316 | .SS FILEATTRSSETPROC |
---|
1317 | .PP |
---|
1318 | Function to process a \fBTcl_FSFileAttrsSet\fR call, used by \fBfile |
---|
1319 | attributes\fR. If the filesystem is read-only, there is no need |
---|
1320 | to implement this. |
---|
1321 | .PP |
---|
1322 | .CS |
---|
1323 | typedef int Tcl_FSFileAttrsSetProc( |
---|
1324 | Tcl_Interp *\fIinterp\fR, |
---|
1325 | int \fIindex\fR, |
---|
1326 | Tcl_Obj *\fIpathPtr\fR, |
---|
1327 | Tcl_Obj *\fIobjPtr\fR); |
---|
1328 | .CE |
---|
1329 | .PP |
---|
1330 | The attribute value of the \fIindex\fR'th element in the list returned by |
---|
1331 | the Tcl_FSFileAttrStringsProc should be set to the \fIobjPtr\fR given. |
---|
1332 | .SS CREATEDIRECTORYPROC |
---|
1333 | .PP |
---|
1334 | Function to process a \fBTcl_FSCreateDirectory\fR call. Should be |
---|
1335 | implemented unless the FS is read-only. |
---|
1336 | .PP |
---|
1337 | .CS |
---|
1338 | typedef int Tcl_FSCreateDirectoryProc( |
---|
1339 | Tcl_Obj *\fIpathPtr\fR); |
---|
1340 | .CE |
---|
1341 | .PP |
---|
1342 | The return value is a standard Tcl result indicating whether an error |
---|
1343 | occurred in the process. If successful, a new directory should have |
---|
1344 | been added to the filesystem in the location specified by |
---|
1345 | \fIpathPtr\fR. |
---|
1346 | .SS REMOVEDIRECTORYPROC |
---|
1347 | .PP |
---|
1348 | Function to process a \fBTcl_FSRemoveDirectory\fR call. Should be |
---|
1349 | implemented unless the FS is read-only. |
---|
1350 | .PP |
---|
1351 | .CS |
---|
1352 | typedef int Tcl_FSRemoveDirectoryProc( |
---|
1353 | Tcl_Obj *\fIpathPtr\fR, |
---|
1354 | int \fIrecursive\fR, |
---|
1355 | Tcl_Obj **\fIerrorPtr\fR); |
---|
1356 | .CE |
---|
1357 | .PP |
---|
1358 | The return value is a standard Tcl result indicating whether an error |
---|
1359 | occurred in the process. If successful, the directory specified by |
---|
1360 | \fIpathPtr\fR should have been removed from the filesystem. If the |
---|
1361 | \fIrecursive\fR flag is given, then a non-empty directory should be |
---|
1362 | deleted without error. If this flag is not given, then and the |
---|
1363 | directory is non-empty a POSIX |
---|
1364 | .QW EEXIST |
---|
1365 | error should be signalled. If an |
---|
1366 | error does occur, the name of the file or directory which caused the |
---|
1367 | error should be placed in \fIerrorPtr\fR. |
---|
1368 | .SS DELETEFILEPROC |
---|
1369 | .PP |
---|
1370 | Function to process a \fBTcl_FSDeleteFile\fR call. Should be implemented |
---|
1371 | unless the FS is read-only. |
---|
1372 | .PP |
---|
1373 | .CS |
---|
1374 | typedef int Tcl_FSDeleteFileProc( |
---|
1375 | Tcl_Obj *\fIpathPtr\fR); |
---|
1376 | .CE |
---|
1377 | .PP |
---|
1378 | The return value is a standard Tcl result indicating whether an error |
---|
1379 | occurred in the process. If successful, the file specified by |
---|
1380 | \fIpathPtr\fR should have been removed from the filesystem. Note that, |
---|
1381 | if the filesystem supports symbolic links, Tcl will always call this |
---|
1382 | function and not Tcl_FSRemoveDirectoryProc when needed to delete them |
---|
1383 | (even if they are symbolic links to directories). |
---|
1384 | .SH "FILESYSTEM EFFICIENCY" |
---|
1385 | .PP |
---|
1386 | These functions need not be implemented for a particular filesystem |
---|
1387 | because the core has a fallback implementation available. See each |
---|
1388 | individual description for the consequences of leaving the field NULL. |
---|
1389 | .SS LSTATPROC |
---|
1390 | .PP |
---|
1391 | Function to process a \fBTcl_FSLstat\fR call. If not implemented, Tcl |
---|
1392 | will attempt to use the \fIstatProc\fR defined above instead. Therefore |
---|
1393 | it need only be implemented if a filesystem can differentiate between |
---|
1394 | \fBstat\fR and \fBlstat\fR calls. |
---|
1395 | .PP |
---|
1396 | .CS |
---|
1397 | typedef int Tcl_FSLstatProc( |
---|
1398 | Tcl_Obj *\fIpathPtr\fR, |
---|
1399 | Tcl_StatBuf *\fIstatPtr\fR); |
---|
1400 | .CE |
---|
1401 | .PP |
---|
1402 | The behavior of this function is very similar to that of the |
---|
1403 | \fBTcl_FSStatProc\fR defined above, except that if it is applied |
---|
1404 | to a symbolic link, it returns information about the link, not |
---|
1405 | about the target file. |
---|
1406 | .SS COPYFILEPROC |
---|
1407 | .PP |
---|
1408 | Function to process a \fBTcl_FSCopyFile\fR call. If not implemented Tcl |
---|
1409 | will fall back on \fBopen\fR-r, \fBopen\fR-w and \fBfcopy\fR as a |
---|
1410 | copying mechanism. |
---|
1411 | Therefore it need only be implemented if the filesystem can perform |
---|
1412 | that action more efficiently. |
---|
1413 | .PP |
---|
1414 | .CS |
---|
1415 | typedef int Tcl_FSCopyFileProc( |
---|
1416 | Tcl_Obj *\fIsrcPathPtr\fR, |
---|
1417 | Tcl_Obj *\fIdestPathPtr\fR); |
---|
1418 | .CE |
---|
1419 | .PP |
---|
1420 | The return value is a standard Tcl result indicating whether an error |
---|
1421 | occurred in the copying process. Note that, \fIdestPathPtr\fR is the |
---|
1422 | name of the file which should become the copy of \fIsrcPathPtr\fR. It |
---|
1423 | is never the name of a directory into which \fIsrcPathPtr\fR could be |
---|
1424 | copied (i.e. the function is much simpler than the Tcl level \fBfile |
---|
1425 | copy\fR subcommand). Note that, |
---|
1426 | if the filesystem supports symbolic links, Tcl will always call this |
---|
1427 | function and not \fIcopyDirectoryProc\fR when needed to copy them |
---|
1428 | (even if they are symbolic links to directories). Finally, if the |
---|
1429 | filesystem determines it cannot support the \fBfile copy\fR action, |
---|
1430 | calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR |
---|
1431 | result will tell Tcl to use its standard fallback mechanisms. |
---|
1432 | .SS RENAMEFILEPROC |
---|
1433 | .PP |
---|
1434 | Function to process a \fBTcl_FSRenameFile\fR call. If not implemented, |
---|
1435 | Tcl will fall back on a copy and delete mechanism. Therefore it need |
---|
1436 | only be implemented if the filesystem can perform that action more |
---|
1437 | efficiently. |
---|
1438 | .PP |
---|
1439 | .CS |
---|
1440 | typedef int Tcl_FSRenameFileProc( |
---|
1441 | Tcl_Obj *\fIsrcPathPtr\fR, |
---|
1442 | Tcl_Obj *\fIdestPathPtr\fR); |
---|
1443 | .CE |
---|
1444 | .PP |
---|
1445 | The return value is a standard Tcl result indicating whether an error |
---|
1446 | occurred in the renaming process. If the |
---|
1447 | filesystem determines it cannot support the \fBfile rename\fR action, |
---|
1448 | calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR |
---|
1449 | result will tell Tcl to use its standard fallback mechanisms. |
---|
1450 | .SS COPYDIRECTORYPROC |
---|
1451 | .PP |
---|
1452 | Function to process a \fBTcl_FSCopyDirectory\fR call. If not |
---|
1453 | implemented, Tcl will fall back on a recursive \fBfile mkdir\fR, \fBfile copy\fR |
---|
1454 | mechanism. Therefore it need only be implemented if the filesystem can |
---|
1455 | perform that action more efficiently. |
---|
1456 | .PP |
---|
1457 | .CS |
---|
1458 | typedef int Tcl_FSCopyDirectoryProc( |
---|
1459 | Tcl_Obj *\fIsrcPathPtr\fR, |
---|
1460 | Tcl_Obj *\fIdestPathPtr\fR, |
---|
1461 | Tcl_Obj **\fIerrorPtr\fR); |
---|
1462 | .CE |
---|
1463 | .PP |
---|
1464 | The return value is a standard Tcl result indicating whether an error |
---|
1465 | occurred in the copying process. If an error does occur, the name of |
---|
1466 | the file or directory which caused the error should be placed in |
---|
1467 | \fIerrorPtr\fR. Note that, \fIdestPathPtr\fR is the name of the |
---|
1468 | directory-name which should become the mirror-image of |
---|
1469 | \fIsrcPathPtr\fR. It is not the name of a directory into which |
---|
1470 | \fIsrcPathPtr\fR should be copied (i.e. the function is much simpler |
---|
1471 | than the Tcl level \fBfile copy\fR subcommand). Finally, if the |
---|
1472 | filesystem determines it cannot support the directory copy action, |
---|
1473 | calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR |
---|
1474 | result will tell Tcl to use its standard fallback mechanisms. |
---|
1475 | .SS LOADFILEPROC |
---|
1476 | .PP |
---|
1477 | Function to process a \fBTcl_FSLoadFile\fR call. If not implemented, Tcl |
---|
1478 | will fall back on a copy to native-temp followed by a \fBTcl_FSLoadFile\fR on |
---|
1479 | that temporary copy. Therefore it need only be implemented if the |
---|
1480 | filesystem can load code directly, or it can be implemented simply to |
---|
1481 | return \fBTCL_ERROR\fR to disable load functionality in this filesystem |
---|
1482 | entirely. |
---|
1483 | .PP |
---|
1484 | .CS |
---|
1485 | typedef int Tcl_FSLoadFileProc( |
---|
1486 | Tcl_Interp *\fIinterp\fR, |
---|
1487 | Tcl_Obj *\fIpathPtr\fR, |
---|
1488 | Tcl_LoadHandle *\fIhandlePtr\fR, |
---|
1489 | Tcl_FSUnloadFileProc *\fIunloadProcPtr\fR); |
---|
1490 | .CE |
---|
1491 | .PP |
---|
1492 | Returns a standard Tcl completion code. If an error occurs, an error |
---|
1493 | message is left in the \fIinterp\fR's result. The function dynamically loads a |
---|
1494 | binary code file into memory. On a successful load, the \fIhandlePtr\fR |
---|
1495 | should be filled with a token for the dynamically loaded file, and the |
---|
1496 | \fIunloadProcPtr\fR should be filled in with the address of a procedure. |
---|
1497 | The unload procedure will be called with the given \fBTcl_LoadHandle\fR as its |
---|
1498 | only parameter when Tcl needs to unload the file. For example, for the |
---|
1499 | native filesystem, the \fBTcl_LoadHandle\fR returned is currently a token |
---|
1500 | which can be used in the private \fBTclpFindSymbol\fR to access functions |
---|
1501 | in the new code. Each filesystem is free to define the |
---|
1502 | \fBTcl_LoadHandle\fR as it requires. Finally, if the |
---|
1503 | filesystem determines it cannot support the file load action, |
---|
1504 | calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR |
---|
1505 | result will tell Tcl to use its standard fallback mechanisms. |
---|
1506 | .SS UNLOADFILEPROC |
---|
1507 | .PP |
---|
1508 | Function to unload a previously successfully loaded file. If load was |
---|
1509 | implemented, then this should also be implemented, if there is any |
---|
1510 | cleanup action required. |
---|
1511 | .PP |
---|
1512 | .CS |
---|
1513 | typedef void Tcl_FSUnloadFileProc( |
---|
1514 | Tcl_LoadHandle \fIloadHandle\fR); |
---|
1515 | .CE |
---|
1516 | .SS GETCWDPROC |
---|
1517 | .PP |
---|
1518 | Function to process a \fBTcl_FSGetCwd\fR call. Most filesystems need not |
---|
1519 | implement this. It will usually only be called once, if \fBgetcwd\fR is |
---|
1520 | called before \fBchdir\fR. May be NULL. |
---|
1521 | .PP |
---|
1522 | .CS |
---|
1523 | typedef Tcl_Obj* Tcl_FSGetCwdProc( |
---|
1524 | Tcl_Interp *\fIinterp\fR); |
---|
1525 | .CE |
---|
1526 | .PP |
---|
1527 | If the filesystem supports a native notion of a current working |
---|
1528 | directory (which might perhaps change independent of Tcl), this |
---|
1529 | function should return that cwd as the result, or NULL if the current |
---|
1530 | directory could not be determined (e.g. the user does not have |
---|
1531 | appropriate permissions on the cwd directory). If NULL is returned, an |
---|
1532 | error message is left in the \fIinterp\fR's result. |
---|
1533 | .SS CHDIRPROC |
---|
1534 | .PP |
---|
1535 | Function to process a \fBTcl_FSChdir\fR call. If filesystems do not |
---|
1536 | implement this, it will be emulated by a series of directory access |
---|
1537 | checks. Otherwise, virtual filesystems which do implement it need only |
---|
1538 | respond with a positive return result if the \fIpathPtr\fR is a valid, |
---|
1539 | accessible directory in their filesystem. They need not remember the |
---|
1540 | result, since that will be automatically remembered for use by |
---|
1541 | \fBTcl_FSGetCwd\fR. |
---|
1542 | Real filesystems should carry out the correct action (i.e. call the |
---|
1543 | correct system \fBchdir\fR API). |
---|
1544 | .PP |
---|
1545 | .CS |
---|
1546 | typedef int Tcl_FSChdirProc( |
---|
1547 | Tcl_Obj *\fIpathPtr\fR); |
---|
1548 | .CE |
---|
1549 | .PP |
---|
1550 | The \fBTcl_FSChdirProc\fR changes the applications current working |
---|
1551 | directory to the value specified in \fIpathPtr\fR. The function returns |
---|
1552 | -1 on error or 0 on success. |
---|
1553 | .SH "SEE ALSO" |
---|
1554 | cd(n), file(n), load(n), open(n), pwd(n), unload(n) |
---|
1555 | .SH KEYWORDS |
---|
1556 | stat, access, filesystem, vfs, virtual |
---|