| 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 |