NAME
       filename - File name conventions supported by Tcl commands

INTRODUCTION
       All Tcl commands and C procedures that take file names  as
       arguments  allow the file names to be in one of two forms:
       native  or  network.   Each  platform  that  Tcl  supports
       defines  a  native  file  naming convention that should be
       familiar to users of  that  platform.   In  addition,  Tcl
       defines  a  file  naming  convention  that  can be used by
       scripts in a  platform  independent  fashion.   Since  the
       characters  used to separate parts of a path name are dif-
       ferent on different platforms,  the  network  file  naming
       convention  should  be  used  by  scripts  that wish to be
       portable.  By choosing file names from a subset  of  those
       allowed  on  the  various  platforms  and by using network
       style paths, a Tcl script can access files without needing
       to know how native paths are constructed.


NATIVE NAMES
       The  rules for native names depend on the current value of
       the Tcl array element tcl_platform(platform):

       mac    On Apple Macintosh platforms, Tcl uses  path  names
              where  the  components  are  separated  by  colons.
              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
              path contains a colon that is not at the beginning,
              then  the  path is interpreted as an absolute path.
              A trailing colon indicates a folder.  If there  are
              no colons, then the name is interpreted relative to
              the current  folder.   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.   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 cur-
                             rent 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.

       unix   On Unix-like 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  direc-
                             tory.

              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 direc-
                             tory.

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

       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          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  direc-
                             tory on the current volume.

              \foo           Absolute  path  to a file foo in the
                             root directory of the  current  vol-
                             ume.


NETWORK NAMES
       Network      names     follow     the     general     form
       //root/export/path.../name.  The //root/export/  component
       refers  to  a  network  host  and export directory, and is
       optional. The leading slash on the path component may also
       be omitted, in which case the path is interpreted relative
       to the current directory.  In addition, network paths must
       conform to the following rules:

       [1]    // may only appear at the beginning of a path.

       [2]    / is used to separate components in the path.

       [3]    \  must  be used to quote characters in the set :/\
              that are used in the middle of a path component.

       [4]    The characters : and \ may not appear unquoted.

       [5]    The first character of a path cannot be a "\".   If
              a path begins with a character that must be quoted,
              then "./" must be prepended to the path.

       All native paths have an  equivalent  network  representa-
       tion.   The  mapping from native to network paths involves
       converting native path separators  into  forward  slashes,
       quoting  embedded  slash, backslash, and colon characters,
       and handling a few special cases:

              Windows drive-relative  paths  are  represented  as
              //?/x\:./path  for relative paths, and //?/x\:/path
              for absolute paths, where x is a drive letter.  For
              example,    c:foo    would    be   represented   as
              //?/c\:./foo.

              Unix paths containing multiple adjacent slashes are
              be  converted  to  an equivalent path containing no
              adjacent slashes.
       Not all network paths have an equivalent native  represen-
       tation.   In  cases where no mapping is possible, Tcl com-
       mands will return an  error.   For  example,  //host/share
       will  cause  an  error  on  Mac and Unix file systems.  In
       cases where a path is ambiguous and could  be  interpreted
       as  either  a  native or a network path, Tcl commands will
       assume a network interpretation.  For  example,  the  file
       foo/bar  could  refer  to  a network file named bar in the
       directory foo, or it could refer to a Macintosh file named
       foo/bar.  Tcl will choose the network name interpretation.
       In order to force the Macintosh interpretation,  a  script
       could use :foo/bar instead.


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.


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 network names to
       construct paths.

       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.


KEYWORDS
       file name, network name, native name
