tcl7.6 User Commands - filename






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 plat-
     form.  In addition, on all platforms, Tcl supports  a  Unix-
     like  syntax  intended  to  provide a convenient way of con-
     structing 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: abso-
     lute, 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 rela-
     tive to the root directory on the current volume,  or  rela-
     tive  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 char-
               acter 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 interpreted as a single separator.
               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 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
                              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 direc-
                              tory 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 vari-
     able 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  substitu-
     tion.

     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,
     volume-relative file name, portability