NAME
       filename - File name conventions supported by Tcl commands

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


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


PATH SYNTAX
       The  rules  for  native  names  depend on the value reported in the Tcl
       array element tcl_platform(platform):

       mac       On Apple Macintosh systems, Tcl supports two  forms  of  path
                 names.  The normal Mac style names use colons as path separa-
                 tors.  Paths may be relative or absolute, and file names  may
                 contain  any  character  other  than  colon.  A leading colon
                 causes the rest of the path to be interpreted relative to the
                 current directory.  If a path contains a colon that is not at
                 the beginning, then the path is interpreted  as  an  absolute
                 path.   Sequences  of two or more colons anywhere in the path
                 are used to construct relative paths where :: refers  to  the
                 parent  of the current directory, ::: refers to the parent of
                 the parent, and so forth.

                 In addition to Macintosh style names,  Tcl  also  supports  a
                 subset  of  Unix-like  names.   If a path contains no colons,
                 then it is interpreted like a Unix path.  Slash  is  used  as
                 the  path  separator.   The file name . refers to the current
                 directory, and .. refers to the parent of the current  direc-
                 tory.  However, some names like / or /.. have no mapping, and
                 are interpreted as Macintosh  names.   In  general,  commands
                 that  generate  file names will return Macintosh style names,
                 but commands that accept file names will take both  Macintosh
                 and Unix-style names.

                 The  following  examples  illustrate  various  forms  of path
                 names:

                 :              Relative path to the current folder.

                 MyFile         Relative path to a file named  MyFile  in  the
                                current folder.

                 MyDisk:MyFile  Absolute  path  to  a file named MyFile on the
                                device named MyDisk.

                 :MyDir:MyFile  Relative path to  a  file  name  MyFile  in  a
                                folder named MyDir in the current folder.

                 ::MyFile       Relative  path  to  a file named MyFile in the
                                folder above the current folder.

                 :::MyFile      Relative path to a file named  MyFile  in  the
                                folder two levels above the current folder.

                 /MyDisk/MyFile Absolute  path  to  a file named MyFile on the
                                device named MyDisk.

                 ../MyFile      Relative path to a file named  MyFile  in  the
                                folder above the current folder.

       unix      On  Unix  platforms, Tcl uses path names where the components
                 are separated by slashes.  Path  names  may  be  relative  or
                 absolute, and file names may contain any character other than
                 slash.  The file names . and .. are special and refer to  the
                 current  directory  and  the  parent of the current directory
                 respectively.  Multiple adjacent slash characters are  inter-
                 preted  as a single separator.  The following examples illus-
                 trate various forms of path names:

                 /              Absolute path to the root directory.

                 /etc/passwd    Absolute path to the file named passwd in  the
                                directory etc in the root directory.

                 .              Relative path to the current directory.

                 foo            Relative  path  to the file foo in the current
                                directory.

                 foo/bar        Relative path to the file bar in the directory
                                foo in the current directory.

                 ../foo         Relative path to the file foo in the directory
                                above the current directory.

       windows   On Microsoft Windows platforms, Tcl supports both drive-rela-
                 tive and UNC style names.  Both / and \ may be used as direc-
                 tory separators in either type of name.  Drive-relative names
                 consist  of  an optional drive specifier followed by an abso-
                 lute or relative path.  UNC paths  follow  the  general  form
                 \\servername\sharename\path\file,  but must at the very least
                 contain the server  and  share  components,  i.e.   \\server-
                 name\sharename.   In  both forms, the file names . and .. are
                 special and refer to the current directory and the parent  of
                 the  current  directory respectively.  The following examples
                 illustrate various forms of path names:

                 \\Host\share/file
                                Absolute UNC path to a file called file in the
                                root  directory  of  the export point share on
                                the host Host.  Note that repeated use of file
                                dirname  on  this path will give //Host/share,
                                and will never give just /fB//Host/fR.

                 c:foo          Volume-relative path to a file foo in the cur-
                                rent directory on drive c.

                 c:/foo         Absolute path to a file foo in the root direc-
                                tory of drive c.

                 foo\bar        Relative path to a file bar in the foo  direc-
                                tory  in  the current directory on the current
                                volume.

                 \foo           Volume-relative path to a file foo in the root
                                directory of the current volume.

                 \\foo          Volume-relative path to a file foo in the root
                                directory of the current volume.  This is  not
                                a  valid  UNC  path, so the assumption is that
                                the extra backslashes are superfluous.


TILDE SUBSTITUTION
       In addition to the file name rules described above, Tcl  also  supports
       csh-style tilde substitution.  If a file name starts with a tilde, then
       the file name will be interpreted as if the first element  is  replaced
       with  the  location  of  the home directory for the given user.  If the
       tilde is followed immediately by a separator, then the  $HOME  environ-
       ment  variable  is  substituted.   Otherwise the characters between the
       tilde and the next separator are taken as a user name, which is used to
       retrieve the user's home directory for substitution.

       The  Macintosh  and Windows platforms do not support tilde substitution
       when a user name follows the tilde.  On these  platforms,  attempts  to
       use  a  tilde  followed  by a user name will generate an error that the
       user does not exist when Tcl attempts to interpret  that  part  of  the
       path  or  otherwise access the file.  The behaviour of these paths when
       not trying to interpret them is the same as on Unix.  File  names  that
       have  a  tilde  without a user name will be correctly substituted using
       the $HOME environment variable, just like for Unix.


PORTABILITY ISSUES
       Not all file systems are case sensitive, so scripts should  avoid  code
       that  depends  on  the case of characters in a file name.  In addition,
       the character sets allowed on different devices may differ, so  scripts
       should  choose  file names that do not contain special characters like:
       <>:"/\|.  The safest approach is to use names  consisting  of  alphanu-
       meric  characters only.  Also Windows 3.1 only supports file names with
       a root of no more than 8 characters and an extension of no more than  3
       characters.

       On Windows platforms there are file and path length restrictions.  Com-
       plete paths or filenames longer than about 260 characters will lead  to
       errors in most file operations.

       Another Windows peculiarity is that any number of trailing dots '.'  in
       filenames are totally ignored, so, for example, attempts  to  create  a
       file  or  directory with a name "foo." will result in the creation of a
       file/directory with name "foo".  This fact is reflected in the  results
       of  'file normalize'.  Furthermore, a file name consisting only of dots
       '.........' or dots with trailing characters '.....abc' is illegal.

KEYWORDS
       current directory, absolute file name, relative file name, volume-rela-
       tive file name, portability


SEE ALSO
