| '\" |
| '\" Copyright (c) 1993 The Regents of the University of California. |
| '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
| '\" |
| '\" See the file "license.terms" for information on usage and redistribution |
| '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| '\" |
| '\" RCS: @(#) $Id: glob.n,v 1.12 2002/07/01 18:24:39 jenglish Exp $ |
| '\" |
| '\" The definitions below are for supplemental macros used in Tcl/Tk |
| '\" manual entries. |
| '\" |
| '\" .AP type name in/out ?indent? |
| '\" Start paragraph describing an argument to a library procedure. |
| '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| '\" or "in/out" to describe whether procedure reads or modifies arg, |
| '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| '\" needed; use .AS below instead) |
| '\" |
| '\" .AS ?type? ?name? |
| '\" Give maximum sizes of arguments for setting tab stops. Type and |
| '\" name are examples of largest possible arguments that will be passed |
| '\" to .AP later. If args are omitted, default tab stops are used. |
| '\" |
| '\" .BS |
| '\" Start box enclosure. From here until next .BE, everything will be |
| '\" enclosed in one large box. |
| '\" |
| '\" .BE |
| '\" End of box enclosure. |
| '\" |
| '\" .CS |
| '\" Begin code excerpt. |
| '\" |
| '\" .CE |
| '\" End code excerpt. |
| '\" |
| '\" .VS ?version? ?br? |
| '\" Begin vertical sidebar, for use in marking newly-changed parts |
| '\" of man pages. The first argument is ignored and used for recording |
| '\" the version when the .VS was added, so that the sidebars can be |
| '\" found and removed when they reach a certain age. If another argument |
| '\" is present, then a line break is forced before starting the sidebar. |
| '\" |
| '\" .VE |
| '\" End of vertical sidebar. |
| '\" |
| '\" .DS |
| '\" Begin an indented unfilled display. |
| '\" |
| '\" .DE |
| '\" End of indented unfilled display. |
| '\" |
| '\" .SO |
| '\" Start of list of standard options for a Tk widget. The |
| '\" options follow on successive lines, in four columns separated |
| '\" by tabs. |
| '\" |
| '\" .SE |
| '\" End of list of standard options for a Tk widget. |
| '\" |
| '\" .OP cmdName dbName dbClass |
| '\" Start of description of a specific option. cmdName gives the |
| '\" option's name as specified in the class command, dbName gives |
| '\" the option's name in the option database, and dbClass gives |
| '\" the option's class in the option database. |
| '\" |
| '\" .UL arg1 arg2 |
| '\" Print arg1 underlined, then print arg2 normally. |
| '\" |
| '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| '\" |
| '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| .if t .wh -1.3i ^B |
| .nr ^l \n(.l |
| .ad b |
| '\" # Start an argument description |
| .de AP |
| .ie !"\\$4"" .TP \\$4 |
| .el \{\ |
| . ie !"\\$2"" .TP \\n()Cu |
| . el .TP 15 |
| .\} |
| .ta \\n()Au \\n()Bu |
| .ie !"\\$3"" \{\ |
| \&\\$1 \\fI\\$2\\fP (\\$3) |
| .\".b |
| .\} |
| .el \{\ |
| .br |
| .ie !"\\$2"" \{\ |
| \&\\$1 \\fI\\$2\\fP |
| .\} |
| .el \{\ |
| \&\\fI\\$1\\fP |
| .\} |
| .\} |
| .. |
| '\" # define tabbing values for .AP |
| .de AS |
| .nr )A 10n |
| .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| .nr )B \\n()Au+15n |
| .\" |
| .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| .. |
| .AS Tcl_Interp Tcl_CreateInterp in/out |
| '\" # BS - start boxed text |
| '\" # ^y = starting y location |
| '\" # ^b = 1 |
| .de BS |
| .br |
| .mk ^y |
| .nr ^b 1u |
| .if n .nf |
| .if n .ti 0 |
| .if n \l'\\n(.lu\(ul' |
| .if n .fi |
| .. |
| '\" # BE - end boxed text (draw box now) |
| .de BE |
| .nf |
| .ti 0 |
| .mk ^t |
| .ie n \l'\\n(^lu\(ul' |
| .el \{\ |
| .\" Draw four-sided box normally, but don't draw top of |
| .\" box if the box started on an earlier page. |
| .ie !\\n(^b-1 \{\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .el \}\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .\} |
| .fi |
| .br |
| .nr ^b 0 |
| .. |
| '\" # VS - start vertical sidebar |
| '\" # ^Y = starting y location |
| '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| .de VS |
| .if !"\\$2"" .br |
| .mk ^Y |
| .ie n 'mc \s12\(br\s0 |
| .el .nr ^v 1u |
| .. |
| '\" # VE - end of vertical sidebar |
| .de VE |
| .ie n 'mc |
| .el \{\ |
| .ev 2 |
| .nf |
| .ti 0 |
| .mk ^t |
| \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| .sp -1 |
| .fi |
| .ev |
| .\} |
| .nr ^v 0 |
| .. |
| '\" # Special macro to handle page bottom: finish off current |
| '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| '\" # page bottom macro. |
| .de ^B |
| .ev 2 |
| 'ti 0 |
| 'nf |
| .mk ^t |
| .if \\n(^b \{\ |
| .\" Draw three-sided box if this is the box's first page, |
| .\" draw two sides but no top otherwise. |
| .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .\} |
| .if \\n(^v \{\ |
| .nr ^x \\n(^tu+1v-\\n(^Yu |
| \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| .\} |
| .bp |
| 'fi |
| .ev |
| .if \\n(^b \{\ |
| .mk ^y |
| .nr ^b 2 |
| .\} |
| .if \\n(^v \{\ |
| .mk ^Y |
| .\} |
| .. |
| '\" # DS - begin display |
| .de DS |
| .RS |
| .nf |
| .sp |
| .. |
| '\" # DE - end display |
| .de DE |
| .fi |
| .RE |
| .sp |
| .. |
| '\" # SO - start of list of standard options |
| .de SO |
| .SH "STANDARD OPTIONS" |
| .LP |
| .nf |
| .ta 5.5c 11c |
| .ft B |
| .. |
| '\" # SE - end of list of standard options |
| .de SE |
| .fi |
| .ft R |
| .LP |
| See the \\fBoptions\\fR manual entry for details on the standard options. |
| .. |
| '\" # OP - start of full description for a single option |
| .de OP |
| .LP |
| .nf |
| .ta 4c |
| Command-Line Name: \\fB\\$1\\fR |
| Database Name: \\fB\\$2\\fR |
| Database Class: \\fB\\$3\\fR |
| .fi |
| .IP |
| .. |
| '\" # CS - begin code excerpt |
| .de CS |
| .RS |
| .nf |
| .ta .25i .5i .75i 1i |
| .. |
| '\" # CE - end code excerpt |
| .de CE |
| .fi |
| .RE |
| .. |
| .de UL |
| \\$1\l'|0\(ul'\\$2 |
| .. |
| .TH glob n 8.3 Tcl "Tcl Built-In Commands" |
| .BS |
| '\" Note: do not modify the .SH NAME line immediately below! |
| .SH NAME |
| glob \- Return names of files that match patterns |
| .SH SYNOPSIS |
| \fBglob \fR?\fIswitches\fR? \fIpattern \fR?\fIpattern ...\fR? |
| .BE |
| |
| .SH DESCRIPTION |
| .PP |
| This command performs file name ``globbing'' in a fashion similar to |
| the csh shell. It returns a list of the files whose names match any |
| of the \fIpattern\fR arguments. |
| .LP |
| If the initial arguments to \fBglob\fR start with \fB\-\fR then |
| they are treated as switches. The following switches are |
| currently supported: |
| .VS 8.3 |
| .TP |
| \fB\-directory\fR \fIdirectory\fR |
| Search for files which match the given patterns starting in the given |
| \fIdirectory\fR. This allows searching of directories whose name |
| contains glob-sensitive characters without the need to quote such |
| characters explicitly. This option may not be used in conjunction with |
| \fB\-path\fR, which is used to allow searching for complete file paths |
| whose names may contain glob-sensitive characters. |
| .TP |
| \fB\-join\fR |
| The remaining pattern arguments are treated as a single pattern |
| obtained by joining the arguments with directory separators. |
| .VE 8.3 |
| .TP |
| \fB\-nocomplain\fR |
| Allows an empty list to be returned without error; without this |
| switch an error is returned if the result list would be empty. |
| .VS 8.3 |
| .TP |
| \fB\-path\fR \fIpathPrefix\fR |
| Search for files with the given \fIpathPrefix\fR where the rest of the name |
| matches the given patterns. This allows searching for files with names |
| similar to a given file (as opposed to a directory) even when the names |
| contain glob-sensitive |
| characters. This option may not be used in conjunction with |
| \fB\-directory\fR. For example, to find all files with the same root name |
| as $path, but differing extensions, you should use \fBglob |
| -path [file rootname $path] .*\fR which will work even if $path contains |
| numerous glob-sensitive characters. |
| .TP |
| \fB\-tails\fR |
| Only return the part of each file found which follows the last directory |
| named in any \fB\-directory\fR or \fB\-path\fR path specification. |
| Thus \fBglob -tails -directory $dir *\fR is equivalent to |
| \fBset pwd [pwd] ; cd $dir ; glob *; cd $pwd\fR. For |
| \fB\-path\fR specifications, the returned names will include the last |
| path segment, so \fBglob -tails -path [file rootname ~/foo.tex] .*\fR |
| will return paths like \fBfoo.aux foo.bib foo.tex\fR etc. |
| .TP |
| \fB\-types\fR \fItypeList\fR |
| Only list files or directories which match \fItypeList\fR, where the items |
| in the list have two forms. The first form is like the \-type option of |
| the Unix find command: |
| \fIb\fR (block special file), |
| \fIc\fR (character special file), |
| \fId\fR (directory), |
| \fIf\fR (plain file), |
| \fIl\fR (symbolic link), |
| \fIp\fR (named pipe), |
| or \fIs\fR (socket), where multiple types may be specified in the list. |
| \fBGlob\fR will return all files which match at least one of the types given. |
| .RS |
| .PP |
| The second form specifies types where all the types given must match. |
| These are \fIr\fR, \fIw\fR, \fIx\fR as file permissions, and |
| \fIreadonly\fR, \fIhidden\fR as special permission cases. On the |
| Macintosh, MacOS types and creators are also supported, where any item |
| which is four characters long is assumed to be a MacOS type |
| (e.g. \fBTEXT\fR). Items which are of the form \fI{macintosh type XXXX}\fR |
| or \fI{macintosh creator XXXX}\fR will match types or creators |
| respectively. Unrecognized types, or specifications of multiple MacOS |
| types/creators will signal an error. |
| .PP |
| The two forms may be mixed, so \fB\-types {d f r w}\fR will find all |
| regular files OR directories that have both read AND write permissions. |
| The following are equivalent: |
| .RS |
| .CS |
| \fBglob \-type d *\fR |
| \fBglob */\fR |
| .CE |
| .RE |
| except that the first case doesn't return the trailing ``/'' and |
| is more platform independent. |
| .RE |
| .VE 8.3 |
| .TP |
| \fB\-\|\-\fR |
| Marks the end of switches. The argument following this one will |
| be treated as a \fIpattern\fR even if it starts with a \fB\-\fR. |
| .PP |
| The \fIpattern\fR arguments may contain any of the following |
| special characters: |
| .TP 10 |
| \fB?\fR |
| Matches any single character. |
| .TP 10 |
| \fB*\fR |
| Matches any sequence of zero or more characters. |
| .TP 10 |
| \fB[\fIchars\fB]\fR |
| Matches any single character in \fIchars\fR. If \fIchars\fR |
| contains a sequence of the form \fIa\fB\-\fIb\fR then any |
| character between \fIa\fR and \fIb\fR (inclusive) will match. |
| .TP 10 |
| \fB\e\fIx\fR |
| Matches the character \fIx\fR. |
| .TP 10 |
| \fB{\fIa\fB,\fIb\fB,\fI...\fR} |
| Matches any of the strings \fIa\fR, \fIb\fR, etc. |
| .LP |
| On Unix, as with csh, a ``.'' at the beginning of a file's name or just |
| after a ``/'' must be matched explicitly or with a {} construct, |
| unless the ``-types hidden'' flag is given (since ``.'' at the beginning |
| of a file's name indicates that it is hidden). On other platforms, |
| files beginning with a ``.'' are handled no differently to any others, |
| except the special directories ``.'' and ``..'' which must be matched |
| explicitly (this is to avoid a recursive pattern like ``glob -join * * |
| * *'' from recursing up the directory hierarchy as well as down). |
| In addition, all ``/'' characters must be matched explicitly. |
| .LP |
| If the first character in a \fIpattern\fR is ``~'' then it refers |
| to the home directory for the user whose name follows the ``~''. |
| If the ``~'' is followed immediately by ``/'' then the value of |
| the HOME environment variable is used. |
| .LP |
| The \fBglob\fR command differs from csh globbing in two ways. |
| First, it does not sort its result list (use the \fBlsort\fR |
| command if you want the list sorted). |
| Second, \fBglob\fR only returns the names of files that actually |
| exist; in csh no check for existence is made unless a pattern |
| contains a ?, *, or [] construct. |
| |
| .SH "PORTABILITY ISSUES" |
| .PP |
| Unlike other Tcl commands that will accept both network and native |
| style names (see the \fBfilename\fR manual entry for details on how |
| native and network names are specified), the \fBglob\fR command only |
| accepts native names. |
| .TP |
| \fBWindows\fR |
| . |
| For Windows UNC names, the servername and sharename components of the path |
| may not contain ?, *, or [] constructs. On Windows NT, if \fIpattern\fR is |
| of the form ``\fB~\fIusername\fB@\fIdomain\fR'' it refers to the home |
| directory of the user whose account information resides on the specified NT |
| domain server. Otherwise, user account information is obtained from |
| the local computer. On Windows 95 and 98, \fBglob\fR accepts patterns |
| like ``.../'' and ``..../'' for successively higher up parent directories. |
| |
| . |
| Since the backslash character has a special meaning to the glob |
| command, glob patterns containing Windows style path separators need |
| special care. The pattern \fIC:\e\efoo\e\e*\fR is interpreted as |
| \fIC:\efoo\e*\fR where \fI\ef\fR will match the single character \fIf\fR |
| and \fI\e*\fR will match the single character \fI*\fR and will not be |
| interpreted as a wildcard character. One solution to this problem is |
| to use the Unix style forward slash as a path separator. Windows style |
| paths can be converted to Unix style paths with the command \fBfile |
| join $path\fR (or \fBfile normalize $path\fR in Tcl 8.4). |
| .TP |
| \fBMacintosh\fR |
| . |
| When using the options, \fB\-directory\fR, \fB\-join\fR or \fB\-path\fR, glob |
| assumes the directory separator for the entire pattern is the standard |
| ``:''. When not using these options, glob examines each pattern argument |
| and uses ``/'' unless the pattern contains a ``:''. |
| |
| .SH "SEE ALSO" |
| file(n) |
| |
| .SH KEYWORDS |
| exist, file, glob, pattern |