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