diff options
Diffstat (limited to 'doc/file.n')
| -rw-r--r-- | doc/file.n | 113 |
1 files changed, 79 insertions, 34 deletions
@@ -104,12 +104,12 @@ within a single filesystem, \fIfile copy\fR will copy soft links (i.e. the links themselves are copied, not the things they point to). Trying to overwrite a non-empty directory, overwrite a directory with a file, or overwrite a file with a directory will all result in errors even if -\fI\-force\fR was specified. Arguments are processed in the order +\fB\-force\fR was specified. Arguments are processed in the order specified, halting at the first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument following the \fB\-\|\-\fR will be treated as a \fIsource\fR even if it starts with a \fB\-\fR. .TP -\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ? +\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? ?\fIpathname\fR ... ? . Removes the file or directory specified by each \fIpathname\fR argument. Non-empty directories will be removed only if the @@ -136,20 +136,26 @@ only contains one path element, then returns If \fIname\fR refers to a root directory, then the root directory is returned. For example, .RS +.PP .CS -\fBfile dirname c:/\fR +\fBfile dirname\fR c:/ .CE +.PP returns \fBc:/\fR. .PP Note that tilde substitution will only be performed if it is necessary to complete the command. For example, +.PP .CS -\fBfile dirname ~/src/foo.c\fR +\fBfile dirname\fR ~/src/foo.c .CE +.PP returns \fB~/src\fR, whereas +.PP .CS -\fBfile dirname ~\fR +\fBfile dirname\fR ~ .CE +.PP returns \fB/home\fR (or something similar). .RE .TP @@ -185,9 +191,11 @@ relative, then it will be joined to the previous file name argument. Otherwise, any earlier arguments will be discarded, and joining will proceed from the current argument. For example, .RS +.PP .CS -\fBfile join a b /foo bar\fR +\fBfile join\fR a b /foo bar .CE +.PP returns \fB/foo/bar\fR. .PP Note that any of the names can contain separators, and that the result @@ -219,9 +227,9 @@ If the user wishes to make a link of a specific type only, (and signal an error if for some reason that is not possible), then the optional \fI\-linktype\fR argument should be given. Accepted values for \fI\-linktype\fR are -.QW \-symbolic +.QW \fB\-symbolic\fR and -.QW \-hard . +.QW \fB\-hard\fR . .PP On Unix, symbolic links can be made to relative paths, and those paths must be relative to the actual \fIlinkName\fR's location (not to the @@ -233,11 +241,9 @@ as relative to the cwd). Furthermore, paths are always expanded to absolute form. When creating links on filesystems that either do not support any links, or do not support the specific type requested, an -error message will be returned. In particular Windows 95, 98 and ME do -not support any links at present, but most Unix platforms support both -symbolic and hard links (the latter for files only) and Windows -NT/2000/XP (on NTFS drives) support symbolic -directory links and hard file links. +error message will be returned. Most Unix platforms support both +symbolic and hard links (the latter for files only). Windows +supports symbolic directory links and hard file links on NTFS drives. .RE .TP \fBfile lstat \fIname varName\fR @@ -249,7 +255,7 @@ is for the link rather than the file it refers to. On systems that do not support symbolic links this option behaves exactly the same as the \fBstat\fR option. .TP -\fBfile mkdir \fIdir\fR ?\fIdir\fR ...? +\fBfile mkdir ?\fIdir\fR ...? . Creates each directory specified. For each pathname \fIdir\fR specified, this command will create all non-existing parent directories as @@ -370,10 +376,14 @@ All other elements will be relative. Path separators will be discarded unless they are needed to ensure that an element is unambiguously relative. For example, under Unix .RS +.PP .CS -file split /foo/~bar/baz +\fBfile split\fR /foo/~bar/baz .CE -returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands +.PP +returns +.QW \fB/\0\0foo\0\0./~bar\0\0baz\fR +to ensure that later commands that use the third component do not attempt to perform tilde substitution. .RE @@ -421,6 +431,25 @@ If \fIname\fR contains no separators then returns \fIname\fR. So, \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all return \fBb\fR. .TP +\fBfile tempfile\fR ?\fInameVar\fR? ?\fItemplate\fR? +'\" TIP #210 +.VS 8.6 +Creates a temporary file and returns a read-write channel opened on that file. +If the \fInameVar\fR is given, it specifies a variable that the name of the +temporary file will be written into; if absent, Tcl will attempt to arrange +for the temporary file to be deleted once it is no longer required. If the +\fItemplate\fR is present, it specifies parts of the template of the filename +to use when creating it (such as the directory, base-name or extension) though +some platforms may ignore some or all of these parts and use a built-in +default instead. +.RS +.PP +Note that temporary files are \fIonly\fR ever created on the native +filesystem. As such, they can be relied upon to be used with operating-system +native APIs and external programs that require a filename. +.RE +.VE 8.6 +.TP \fBfile type \fIname\fR . Returns a string giving the type of file \fIname\fR, which will be one of @@ -450,39 +479,49 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user, . These commands always operate using the real user and group identifiers, not the effective ones. +.TP +\fBWindows\fR\0\0\0\0 +. +The \fBfile owned\fR subcommand currently always reports that the current user +is the owner of the file, without regard for what the operating system +believes to be true, making an ownership test useless. This issue (#3613671) +may be fixed in a future release of Tcl. .SH EXAMPLES +.PP This procedure shows how to search for C files in a given directory that have a correspondingly-named object file in the current directory: +.PP .CS proc findMatchingCFiles {dir} { - set files {} - switch $::tcl_platform(platform) { - windows { - set ext .obj - } - unix { - set ext .o - } - } - foreach file [glob \-nocomplain \-directory $dir *.c] { - set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext - if {[\fBfile exists\fR $objectFile]} { - lappend files $file - } - } - return $files + set files {} + switch $::tcl_platform(platform) { + windows { + set ext .obj + } + unix { + set ext .o + } + } + foreach file [glob \-nocomplain \-directory $dir *.c] { + set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext + if {[\fBfile exists\fR $objectFile]} { + lappend files $file + } + } + return $files } .CE .PP Rename a file and leave a symbolic link pointing from the old location to the new place: +.PP .CS set oldName foobar.txt set newName foo/bar.txt # Make sure that where we're going to move to exists... if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} { - \fBfile mkdir\fR [\fBfile dirname\fR $newName] + \fBfile mkdir\fR [\fBfile dirname\fR $newName] } \fBfile rename\fR $oldName $newName \fBfile link\fR \-symbolic $oldName $newName @@ -493,6 +532,7 @@ On Windows, a file can be easily enough (equivalent to double-clicking on it in the Explorer interface) but the name passed to the operating system must be in native format: +.PP .CS exec {*}[auto_execok start] {} [\fBfile nativename\fR ~/example.txt] .CE @@ -500,4 +540,9 @@ exec {*}[auto_execok start] {} [\fBfile nativename\fR ~/example.txt] filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n), fblocked(n), flush(n) .SH KEYWORDS -attributes, copy files, delete files, directory, file, move files, name, rename files, stat +attributes, copy files, delete files, directory, file, move files, name, +rename files, stat, user +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: |