1filename(n)                  Tcl Built-In Commands                 filename(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       filename - File name conventions supported by Tcl commands
9_________________________________________________________________
10

INTRODUCTION

12       All  Tcl  commands  and  C procedures that take file names as arguments
13       expect the file names to be in one of three  forms,  depending  on  the
14       current  platform.   On  each  platform, Tcl supports file names in the
15       standard forms(s) for that platform.  In addition,  on  all  platforms,
16       Tcl supports a Unix-like syntax intended to provide a convenient way of
17       constructing simple file names.  However, scripts that are intended  to
18       be  portable  should  not  assume  a  particular  form  for file names.
19       Instead, portable scripts must use the file split and  file  join  com‐
20       mands  to  manipulate  file  names  (see the file manual entry for more
21       details).
22

PATH TYPES

24       File names are grouped into three general types based on  the  starting
25       point  for  the  path used to specify the file: absolute, relative, and
26       volume-relative.  Absolute names are  completely  qualified,  giving  a
27       path to the file relative to a particular volume and the root directory
28       on that volume.  Relative names are unqualified, giving a path  to  the
29       file  relative to the current working directory.  Volume-relative names
30       are partially qualified, either giving the path relative  to  the  root
31       directory  on  the current volume, or relative to the current directory
32       of the specified volume.  The file pathtype  command  can  be  used  to
33       determine the type of a given path.
34

PATH SYNTAX

36       The  rules  for  native  names  depend on the value reported in the Tcl
37       array element tcl_platform(platform):
38
39       Unix      On Unix and Apple MacOS X  platforms,  Tcl  uses  path  names
40                 where  the  components  are separated by slashes.  Path names
41                 may be relative or absolute, and file names may  contain  any
42                 character other than slash.  The file names . and .. are spe‐
43                 cial and refer to the current directory and the parent of the
44                 current  directory  respectively.   Multiple  adjacent  slash
45                 characters are interpreted as a single separator.  Any number
46                 of  trailing slash characters at the end of a path are simply
47                 ignored, so the paths foo, foo/ and foo// are all  identical,
48                 and  in particular foo/ does not necessarily mean a directory
49                 is being referred.
50
51                 The following  examples  illustrate  various  forms  of  path
52                 names:
53
54                 /              Absolute path to the root directory.
55
56                 /etc/passwd    Absolute  path to the file named passwd in the
57                                directory etc in the root directory.
58
59                 .              Relative path to the current directory.
60
61                 foo            Relative path to the file foo in  the  current
62                                directory.
63
64                 foo/bar        Relative path to the file bar in the directory
65                                foo in the current directory.
66
67                 ../foo         Relative path to the file foo in the directory
68                                above the current directory.
69
70       Windows   On Microsoft Windows platforms, Tcl supports both drive-rela‐
71                 tive and UNC style names.  Both / and \ may be used as direc‐
72                 tory separators in either type of name.  Drive-relative names
73                 consist of an optional drive specifier followed by  an  abso‐
74                 lute  or  relative  path.   UNC paths follow the general form
75                 \\servername\sharename\path\file, but must at the very  least
76                 contain  the  server  and  share  components, i.e.  \\server‐
77                 name\sharename.  In both forms, the file names . and  ..  are
78                 special  and refer to the current directory and the parent of
79                 the current directory respectively.  The  following  examples
80                 illustrate various forms of path names:
81
82                 \\Host\share/file
83                                Absolute UNC path to a file called file in the
84                                root directory of the export  point  share  on
85                                the host Host.  Note that repeated use of file
86                                dirname on this path will  give  //Host/share,
87                                and will never give just //Host.
88
89                 c:foo          Volume-relative path to a file foo in the cur‐
90                                rent directory on drive c.
91
92                 c:/foo         Absolute path to a file foo in the root direc‐
93                                tory of drive c.
94
95                 foo\bar        Relative  path to a file bar in the foo direc‐
96                                tory in the current directory on  the  current
97                                volume.
98
99                 \foo           Volume-relative path to a file foo in the root
100                                directory of the current volume.
101
102                 \\foo          Volume-relative path to a file foo in the root
103                                directory  of the current volume.  This is not
104                                a valid UNC path, so the  assumption  is  that
105                                the extra backslashes are superfluous.
106

TILDE SUBSTITUTION

108       In  addition  to the file name rules described above, Tcl also supports
109       csh-style tilde substitution.  If a file name starts with a tilde, then
110       the  file  name will be interpreted as if the first element is replaced
111       with the location of the home directory for the  given  user.   If  the
112       tilde  is  followed immediately by a separator, then the $HOME environ‐
113       ment variable is substituted.  Otherwise  the  characters  between  the
114       tilde and the next separator are taken as a user name, which is used to
115       retrieve the user's home directory for  substitution.   This  works  on
116       Unix, MacOS X and Windows (except very old releases).
117
118       Old  Windows  platforms  do  not support tilde substitution when a user
119       name follows the tilde.  On these platforms, attempts to  use  a  tilde
120       followed  by  a user name will generate an error that the user does not
121       exist when Tcl attempts to interpret that part of the path or otherwise
122       access  the  file.   The  behaviour  of  these paths when not trying to
123       interpret them is the same as on Unix.  File names that  have  a  tilde
124       without a user name will be correctly substituted using the $HOME envi‐
125       ronment variable, just like for Unix.
126

PORTABILITY ISSUES

128       Not all file systems are case sensitive, so scripts should  avoid  code
129       that  depends  on  the case of characters in a file name.  In addition,
130       the character sets allowed on different devices may differ, so  scripts
131       should  choose  file names that do not contain special characters like:
132       <>:?"/\|.  The safest approach is to use names consisting  of  alphanu‐
133       meric  characters only.  Care should be taken with filenames which con‐
134       tain spaces (common on Windows systems) and filenames where  the  back‐
135       slash  is  the  directory  separator (Windows native path names).  Also
136       Windows 3.1 only supports file names with a root  of  no  more  than  8
137       characters and an extension of no more than 3 characters.
138
139       On Windows platforms there are file and path length restrictions.  Com‐
140       plete paths or filenames longer than about 260 characters will lead  to
141       errors in most file operations.
142
143       Another Windows peculiarity is that any number of trailing dots “.”  in
144       filenames are totally ignored, so, for example, attempts  to  create  a
145       file  or directory with a name “foo.”  will result in the creation of a
146       file/directory with name “foo”.  This fact is reflected in the  results
147       of  file  normalize.   Furthermore, a file name consisting only of dots
148       “.........”  or dots with trailing characters “.....abc” is illegal.
149

SEE ALSO

151       file(n), glob(n)
152

KEYWORDS

154       current directory, absolute file name, relative file name, volume-rela‐
155       tive file name, portability
156
157
158
159Tcl                                   7.5                          filename(n)
Impressum