diff options
Diffstat (limited to 'doc/file.n')
| -rw-r--r-- | doc/file.n | 105 |
1 files changed, 76 insertions, 29 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 @@ -249,7 +257,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 +378,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 +433,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 +481,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 +534,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 +542,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: |