Debian Codegraph @

upstream/debian-unstable/man7/glob.7

raw
1 .\" Copyright 1998, Andries E. Brouwer <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH glob 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 glob \- globbing pathnames
9 .SH DESCRIPTION
10 Long ago, in UNIX\ V6, there was a program
11 .I /etc/glob
12 that would expand wildcard patterns.
13 Soon afterward this became a shell built-in.
14 .P
15 These days there is also a library routine
16 .BR glob (3)
17 that will perform this function for a user program.
18 .P
19 The rules are as follows (POSIX.2, 3.13).
20 .SS Wildcard matching
21 A string is a wildcard pattern if it contains one of the
22 characters \[aq]?\[aq], \[aq]*\[aq], or \[aq][\[aq].
23 Globbing is the operation
24 that expands a wildcard pattern into the list of pathnames
25 matching the pattern.
26 Matching is defined by:
27 .P
28 A \[aq]?\[aq] (not between brackets) matches any single character.
29 .P
30 A \[aq]*\[aq] (not between brackets) matches any string,
31 including the empty string.
32 .P
33 .B "Character classes"
34 .P
35 An expression
36 .RI \[dq] [...] \[dq]
37 where the first character after the
38 leading \[aq][\[aq] is not an \[aq]!\[aq] matches a single character,
39 namely any of the characters enclosed by the brackets.
40 The string enclosed by the brackets cannot be empty;
41 therefore \[aq]]\[aq] can be allowed between the brackets, provided
42 that it is the first character.
43 (Thus,
44 .RI \[dq] [][!] \[dq]
45 matches the
46 three characters \[aq][\[aq], \[aq]]\[aq], and \[aq]!\[aq].)
47 .P
48 .B Ranges
49 .P
50 There is one special convention:
51 two characters separated by \[aq]\-\[aq] denote a range.
52 (Thus,
53 .RI \[dq] [A\-Fa\-f0\-9] \[dq]
54 is equivalent to
55 .RI \[dq] [ABCDEFabcdef0123456789] \[dq].)
56 One may include \[aq]\-\[aq] in its literal meaning
57 by making it the first or last character between the brackets.
58 (Thus,
59 .RI \[dq] []\-] \[dq]
60 matches just the two characters \[aq]]\[aq] and \[aq]\-\[aq],
61 and
62 .RI \[dq] [\-\-0] \[dq]
63 matches the
64 three characters \[aq]\-\[aq], \[aq].\[aq], and \[aq]0\[aq],
65 since \[aq]/\[aq] cannot be matched.)
66 .P
67 .B Complementation
68 .P
69 An expression
70 .RI \[dq] [!...] \[dq]
71 matches a single character, namely
72 any character that is not matched by the expression obtained
73 by removing the first \[aq]!\[aq] from it.
74 (Thus,
75 .RI \[dq] [!]a\-] \[dq]
76 matches any
77 single character except \[aq]]\[aq], \[aq]a\[aq], and \[aq]\-\[aq].)
78 .P
79 One can remove the special meaning of \[aq]?\[aq], \[aq]*\[aq], and \[aq][\[aq]
80 by preceding them by a backslash,
81 or,
82 in case this is part of a shell command line,
83 enclosing them in quotes.
84 Between brackets these characters stand for themselves.
85 Thus,
86 .RI \[dq] [[?*\[rs]] \[dq]
87 matches the
88 four characters \[aq][\[aq], \[aq]?\[aq], \[aq]*\[aq], and \[aq]\[rs]\[aq].
89 .SS Pathnames
90 Globbing is applied on each of the components of a pathname
91 separately.
92 A \[aq]/\[aq] in a pathname cannot be matched by a \[aq]?\[aq] or \[aq]*\[aq]
93 wildcard, or by a range like
94 .RI \[dq] [.\-0] \[dq].
95 A range containing an explicit \[aq]/\[aq] character is syntactically incorrect.
96 (POSIX requires that syntactically incorrect patterns are left unchanged.)
97 .P
98 If a filename starts with a \[aq].\[aq],
99 this character must be matched explicitly.
100 (Thus,
101 .I rm\ *
102 will not remove
103 .IR .profile ,
104 and
105 .I tar\ c\ *
106 will not archive all your files;
107 .I tar\ c\ .
108 is better.)
109 .SS Empty lists
110 The nice and simple rule given above: "expand a wildcard pattern
111 into the list of matching pathnames" was the original UNIX
112 definition.
113 It allowed one to have patterns that expand into
114 an empty list, as in
115 .P
116 .nf
117 xv \-wait 0 *.gif *.jpg
118 .fi
119 .P
120 where perhaps no *.gif files are present (and this is not
121 an error).
122 However, POSIX requires that a wildcard pattern is left
123 unchanged when it is syntactically incorrect, or the list of
124 matching pathnames is empty.
125 With
126 .I bash
127 one can force the classical behavior using this command:
128 .P
129 .in +4n
130 .EX
131 shopt \-s nullglob
132 .EE
133 .in
134 .\" In Bash v1, by setting allow_null_glob_expansion=true
135 .P
136 (Similar problems occur elsewhere.
137 For example, where old scripts have
138 .P
139 .in +4n
140 .EX
141 rm \`find . \-name "*\[ti]"\`
142 .EE
143 .in
144 .P
145 new scripts require
146 .P
147 .in +4n
148 .EX
149 rm \-f nosuchfile \`find . \-name "*\[ti]"\`
150 .EE
151 .in
152 .P
153 to avoid error messages from
154 .I rm
155 called with an empty argument list.)
156 .SH NOTES
157 .SS Regular expressions
158 Note that wildcard patterns are not regular expressions,
159 although they are a bit similar.
160 First of all, they match
161 filenames, rather than text, and secondly, the conventions
162 are not the same: for example, in a regular expression \[aq]*\[aq] means zero or
163 more copies of the preceding thing.
164 .P
165 Now that regular expressions have bracket expressions where
166 the negation is indicated by a \[aq]\[ha]\[aq], POSIX has declared the
167 effect of a wildcard pattern
168 .RI \[dq] [\[ha]...] \[dq]
169 to be undefined.
170 .SS Character classes and internationalization
171 Of course ranges were originally meant to be ASCII ranges,
172 so that
173 .RI \[dq] "[\ \-%]" \[dq]
174 stands for
175 .RI \[dq] "[\ !\[dq]#$%]" \[dq]
176 and
177 .RI \[dq] [a\-z] \[dq]
178 stands
179 for "any lowercase letter".
180 Some UNIX implementations generalized this so that a range X\-Y
181 stands for the set of characters with code between the codes for
182 X and for Y.
183 However, this requires the user to know the
184 character coding in use on the local system, and moreover, is
185 not convenient if the collating sequence for the local alphabet
186 differs from the ordering of the character codes.
187 Therefore, POSIX extended the bracket notation greatly,
188 both for wildcard patterns and for regular expressions.
189 In the above we saw three types of items that can occur in a bracket
190 expression: namely (i) the negation, (ii) explicit single characters,
191 and (iii) ranges.
192 POSIX specifies ranges in an internationally
193 more useful way and adds three more types:
194 .P
195 (iii) Ranges X\-Y comprise all characters that fall between X
196 and Y (inclusive) in the current collating sequence as defined
197 by the
198 .B LC_COLLATE
199 category in the current locale.
200 .P
201 (iv) Named character classes, like
202 .P
203 .nf
204 [:alnum:] [:alpha:] [:blank:] [:cntrl:]
205 [:digit:] [:graph:] [:lower:] [:print:]
206 [:punct:] [:space:] [:upper:] [:xdigit:]
207 .fi
208 .P
209 so that one can say
210 .RI \[dq] [[:lower:]] \[dq]
211 instead of
212 .RI \[dq] [a\-z] \[dq],
213 and have things work in Denmark, too,
214 where there are three letters past \[aq]z\[aq]
215 in the alphabet.
216 These character classes are defined by the
217 .B LC_CTYPE
218 category
219 in the current locale.
220 .P
221 (v) Collating symbols, like
222 .RI \[dq] [.ch.] \[dq]
223 or
224 .RI \[dq] [.a-acute.] \[dq],
225 where the string between
226 .RI \[dq] [. \[dq]
227 and
228 .RI \[dq] .] \[dq]
229 is a collating element defined for the current locale.
230 Note that this may
231 be a multicharacter element.
232 .P
233 (vi) Equivalence class expressions, like
234 .RI \[dq] [=a=] \[dq],
235 where the string between
236 .RI \[dq] [= \[dq]
237 and
238 .RI \[dq] =] \[dq]
239 is any collating element from its equivalence class,
240 as defined for the current locale.
241 For example,
242 .RI \[dq] [[=a=]] \[dq]
243 might be equivalent to
244 .RI \[dq] [a\('a\(`a\(:a\(^a] \[dq],
245 that is, to
246 .RI \[dq] [a[.a-acute.][.a-grave.][.a-umlaut.][.a-circumflex.]] \[dq].
247 .SH SEE ALSO
248 .BR sh (1),
249 .BR fnmatch (3),
250 .BR glob (3),
251 .BR locale (7),
252 .BR regex (7)