summaryrefslogtreecommitdiffstats
path: root/doc/file.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/file.n')
-rw-r--r--doc/file.n105
1 files changed, 76 insertions, 29 deletions
diff --git a/doc/file.n b/doc/file.n
index b62d252..0b0ee9d 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -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: