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
       commands 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  separators.  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 directory.  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   interpreted   as   a   single
                 separator.   The  following  examples illustrate
                 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-relative and UNC style names.  Both /
                 and  \  may  be  used as directory separators in
                 either  type  of  name.   Drive-relative   names
                 consist  of an optional drive specifier followed
                 by an absolute  or  relative  path.   UNC  paths
                 follow          the         general         form
                 \\servername\sharename\path\file.     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.

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

                 c:/foo         Absolute path to a  file  foo  in
                                the root directory of drive c.

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

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


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 environment 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.  File  names  that  have  a  tilde
       without  a  user  name will be 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 alphanumeric 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.


KEYWORDS
       current directory, absolute file name, relative file name,
