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  plat-
       form, Tcl supports file names in the standard forms(s) for
       that platform.  In addition, on all  platforms,  Tcl  sup-
       ports  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 par-
       ticular form for file names.   Instead,  portable  scripts
       must  use the file split and file join commands to manipu-
       late 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  rela-
       tive 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.  Vol-
       ume-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 speci-
       fied  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 par-
                 ent, 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 separa-
                 tor.  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 gen-
                 erate  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 separa-
                 tor.  The following examples illustrate  various
                 forms of path names:

                 /              Absolute  path to the root direc-
                                tory.

                 /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 con-
                 sist of an optional drive specifier followed  by
                 an  absolute or relative path.  UNC paths follow
                 the     general     form     \\servername\share-
                 name\path\file,  but must at the very least con-
                 tain  the  server  and  share  components,  i.e.
                 \\servername\sharename.  In both forms, the file
                 names . and .. are special and refer to the cur-
                 rent  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 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.

                 \\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 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 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 vari-
       able, 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 charac-
       ters and an extension of no more than 3 characters.

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


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


SEE ALSO
