distrib/share/tcl/help/tcl/files/glob

   1 NAME
   2        glob - Return names of files that match patterns
   3
   4 SYNOPSIS
   5        glob ?switches? pattern ?pattern ...?
   6
   7
   8 DESCRIPTION
   9        This  command  performs  file name ``globbing'' in a fashion similar to
  10        the csh shell.  It returns a list of the files whose names match any of
  11        the pattern arguments.
  12
  13        If  the initial arguments to glob start with - then they are treated as
  14        switches.  The following switches are currently supported:
  15
  16        -directory directory
  17               Search for files which match the given patterns starting in  the
  18               given  directory.   This  allows  searching of directories whose
  19               name contains glob-sensitive  characters  without  the  need  to
  20               quote  such  characters explicitly.  This option may not be used
  21               in conjunction with -path, which is used to allow searching  for
  22               complete file paths whose names may contain glob-sensitive char-
  23               acters.
  24
  25        -join  The remaining pattern arguments are treated as a single  pattern
  26               obtained by joining the arguments with directory separators.
  27
  28        -nocomplain
  29               Allows an empty list to be returned without error;  without this
  30               switch an error is returned if the result list would be empty.
  31
  32        -path pathPrefix
  33               Search for files with the given pathPrefix where the rest of the
  34               name  matches  the  given  patterns.   This allows searching for
  35               files with names similar to a given file (as opposed to a direc-
  36               tory)  even  when  the  names contain glob-sensitive characters.
  37               This option may not be used in conjunction with -directory.  For
  38               example, to find all files with the same root name as $path, but
  39               differing extensions, you should use glob -path  [file  rootname
  40               $path]  .* which will work even if $path contains numerous glob-
  41               sensitive characters.
  42
  43        -tails Only return the part of each file found which follows  the  last
  44               directory  named  in any -directory or -path path specification.
  45               Thus glob -tails -directory $dir *  is  equivalent  to  set  pwd
  46               [pwd]  ;  cd  $dir ; glob *; cd $pwd.  For -path specifications,
  47               the returned names will include the last path segment,  so  glob
  48               -tails  -path  [file  rootname  ~/foo.tex] .*  will return paths
  49               like foo.aux foo.bib foo.tex etc.
  50
  51        -types typeList
  52               Only list files or directories which match typeList,  where  the
  53               items  in  the  list have two forms.  The first form is like the
  54               -type option of the Unix find command: b (block special file), c
  55               (character special file), d (directory), f (plain file), l (sym-
  56               bolic link), p (named pipe), or s (socket), where multiple types
  57               may  be specified in the list.  Glob will return all files which
  58               match at least one of the types given.  Note that symbolic links
  59               will  be returned both if -types l is given, or if the target of
  60               a link matches the requested type.  So, a link  to  a  directory
  61               will be returned if -types d was specified.
  62
  63               The  second  form specifies types where all the types given must
  64               match.  These are r, w, x as  file  permissions,  and  readonly,
  65               hidden  as  special  permission  cases.  On the Macintosh, MacOS
  66               types and creators are also supported, where any item  which  is
  67               four  characters long is assumed to be a MacOS type (e.g. TEXT).
  68               Items which are of the form {macintosh type XXXX} or  {macintosh
  69               creator XXXX} will match types or creators respectively.  Unrec-
  70               ognized types, or specifications of  multiple  MacOS  types/cre-
  71               ators will signal an error.
  72
  73               The  two  forms  may be mixed, so -types {d f r w} will find all
  74               regular files OR directories that have both read AND write  per-
  75               missions.  The following are equivalent:
  76                             glob -type d *
  77                             glob */
  78               except that the first case doesn't return the trailing ``/'' and
  79               is more platform independent.
  80
  81        --     Marks the end of switches.  The argument following this one will
  82               be treated as a pattern even if it starts with a -.
  83
  84        The  pattern arguments may contain any of the following special charac-
  85        ters:
  86
  87        ?         Matches any single character.
  88
  89        *         Matches any sequence of zero or more characters.
  90
  91        [chars]   Matches any single character in chars.  If chars  contains  a
  92                  sequence  of  the form a-b then any character between a and b
  93                  (inclusive) will match.
  94
  95        \x        Matches the character x.
  96
  97        {a,b,...} Matches any of the strings a, b, etc.
  98
  99        On Unix, as with csh, a ``.'' at the beginning of a file's name or just
 100        after a ``/'' must be matched explicitly or with a {} construct, unless
 101        the ``-types hidden'' flag is given (since ``.'' at the beginning of  a
 102        file's  name  indicates  that it is hidden).  On other platforms, files
 103        beginning with a ``.'' are handled no differently to any others, except
 104        the  special directories ``.'' and ``..'' which must be matched explic-
 105        itly (this is to avoid a recursive pattern like ``glob -join * * *  *''
 106        from  recursing  up the directory hierarchy as well as down).  In addi-
 107        tion, all ``/'' characters must be matched explicitly.
 108
 109        If the first character in a pattern is ``~'' then it refers to the home
 110        directory  for  the user whose name follows the ``~''.  If the ``~'' is
 111        followed immediately by ``/'' then the value of  the  HOME  environment
 112        variable is used.
 113
 114        The glob command differs from csh globbing in two ways.  First, it does
 115        not sort its result list (use the lsort command if you  want  the  list
 116        sorted).   Second,  glob  only returns the names of files that actually
 117        exist;  in csh no check for existence is made unless a pattern contains
 118        a ?, *, or [] construct.
 119
 120        When the glob command returns relative paths whose filenames start with
 121        a tilde ``~'' (for example through glob * or glob -tails, the  returned
 122        list  will  not  quote  the tilde with ``./''.  This means care must be
 123        taken if those names are later to be used with file join, to avoid them
 124        being  interpreted  as  absolute  paths pointing to a given user's home
 125        directory.
 126
 127 PORTABILITY ISSUES
 128        Unlike other Tcl commands that will  accept  both  network  and  native
 129        style  names  (see  the filename manual entry for details on how native
 130        and network names are specified), the glob command only accepts  native
 131        names.
 132
 133        Windows
 134               For  Windows  UNC names, the servername and sharename components
 135               of the path may not contain ?, *, or [] constructs.  On  Windows
 136               NT,  if pattern is of the form ``~username@domain'' it refers to
 137               the home directory of the user whose account information resides
 138               on  the  specified  NT  domain  server.  Otherwise, user account
 139               information is obtained from the local computer.  On Windows  95
 140               and  98,  glob  accepts patterns like ``.../'' and ``..../'' for
 141               successively higher up parent directories.
 142
 143               Since the backslash character has a special meaning to the  glob
 144               command,  glob patterns containing Windows style path separators
 145               need special care. The  pattern  C:\\foo\\*  is  interpreted  as
 146               C:\foo\*  where \f will match the single character f and \* will
 147               match the single character * and will not be  interpreted  as  a
 148               wildcard  character.  One solution to this problem is to use the
 149               Unix style forward slash as  a  path  separator.  Windows  style
 150               paths can be converted to Unix style paths with the command file
 151               join $path (or file normalize $path in Tcl 8.4).
 152
 153        Macintosh
 154               When using the options, -directory, -join or -path, glob assumes
 155               the  directory  separator for the entire pattern is the standard
 156               ``:''.  When not using these options, glob examines each pattern
 157               argument and uses ``/'' unless the pattern contains a ``:''.
 158
 159 EXAMPLES
 160        Find all the Tcl files in the current directory:
 161               glob *.tcl
 162
 163        Find  all  the  Tcl files in the user's home directory, irrespective of
 164        what the current directory is:
 165               glob -directory ~ *.tcl
 166
 167        Find all subdirectories of the current directory:
 168               glob -type d *
 169
 170        Find all files whose name contains an "a", a "b" or the sequence "cde":
 171               glob -type f *{a,b,cde}*
 172
 173
 174 SEE ALSO
 175        file(n)
 176
 177
 178 KEYWORDS