(Feature Test Macros): Add _POSIX_C_SOURCE definition.
[kopensolaris-gnu/glibc.git] / manual / pattern.texi
1 @node Pattern Matching, I/O Overview, Searching and Sorting, Top
2 @chapter Pattern Matching
3
4 The GNU C Library provides pattern matching facilities for two kinds of
5 patterns: regular expressions and file-name wildcards.  The library also
6 provides a facility for expanding variable and command references and
7 parsing text into words in the way the shell does.
8
9 @menu
10 * Wildcard Matching::    Matching a wildcard pattern against a single string.
11 * Globbing::             Finding the files that match a wildcard pattern.
12 * Regular Expressions::  Matching regular expressions against strings.
13 * Word Expansion::       Expanding shell variables, nested commands,
14                             arithmetic, and wildcards.
15                             This is what the shell does with shell commands.
16 @end menu
17
18 @node Wildcard Matching
19 @section Wildcard Matching
20
21 @pindex fnmatch.h
22 This section describes how to match a wildcard pattern against a
23 particular string.  The result is a yes or no answer: does the
24 string fit the pattern or not.  The symbols described here are all
25 declared in @file{fnmatch.h}.
26
27 @comment fnmatch.h
28 @comment POSIX.2
29 @deftypefun int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})
30 This function tests whether the string @var{string} matches the pattern
31 @var{pattern}.  It returns @code{0} if they do match; otherwise, it
32 returns the nonzero value @code{FNM_NOMATCH}.  The arguments
33 @var{pattern} and @var{string} are both strings.
34
35 The argument @var{flags} is a combination of flag bits that alter the
36 details of matching.  See below for a list of the defined flags.
37
38 In the GNU C Library, @code{fnmatch} cannot experience an ``error''---it
39 always returns an answer for whether the match succeeds.  However, other
40 implementations of @code{fnmatch} might sometimes report ``errors''.
41 They would do so by returning nonzero values that are not equal to
42 @code{FNM_NOMATCH}.
43 @end deftypefun
44
45 These are the available flags for the @var{flags} argument:
46
47 @table @code
48 @comment fnmatch.h
49 @comment GNU
50 @item FNM_FILE_NAME
51 Treat the @samp{/} character specially, for matching file names.  If
52 this flag is set, wildcard constructs in @var{pattern} cannot match
53 @samp{/} in @var{string}.  Thus, the only way to match @samp{/} is with
54 an explicit @samp{/} in @var{pattern}.
55
56 @comment fnmatch.h
57 @comment POSIX.2
58 @item FNM_PATHNAME
59 This is an alias for @code{FNM_FILE_NAME}; it comes from POSIX.2.  We
60 don't recommend this name because we don't use the term ``pathname'' for
61 file names.
62
63 @comment fnmatch.h
64 @comment POSIX.2
65 @item FNM_PERIOD
66 Treat the @samp{.} character specially if it appears at the beginning of
67 @var{string}.  If this flag is set, wildcard constructs in @var{pattern}
68 cannot match @samp{.} as the first character of @var{string}.
69
70 If you set both @code{FNM_PERIOD} and @code{FNM_FILE_NAME}, then the
71 special treatment applies to @samp{.} following @samp{/} as well as to
72 @samp{.} at the beginning of @var{string}.  (The shell uses the
73 @code{FNM_PERIOD} and @code{FNM_FILE_NAME} flags together for matching
74 file names.)
75
76 @comment fnmatch.h
77 @comment POSIX.2
78 @item FNM_NOESCAPE
79 Don't treat the @samp{\} character specially in patterns.  Normally,
80 @samp{\} quotes the following character, turning off its special meaning
81 (if any) so that it matches only itself.  When quoting is enabled, the
82 pattern @samp{\?} matches only the string @samp{?}, because the question
83 mark in the pattern acts like an ordinary character.
84
85 If you use @code{FNM_NOESCAPE}, then @samp{\} is an ordinary character.
86
87 @comment fnmatch.h
88 @comment GNU
89 @item FNM_LEADING_DIR
90 Ignore a trailing sequence of characters starting with a @samp{/} in
91 @var{string}; that is to say, test whether @var{string} starts with a
92 directory name that @var{pattern} matches.
93
94 If this flag is set, either @samp{foo*} or @samp{foobar} as a pattern
95 would match the string @samp{foobar/frobozz}.
96
97 @comment fnmatch.h
98 @comment GNU
99 @item FNM_CASEFOLD
100 Ignore case in comparing @var{string} to @var{pattern}.
101 @end table
102
103 @node Globbing
104 @section Globbing
105
106 @cindex globbing
107 The archetypal use of wildcards is for matching against the files in a
108 directory, and making a list of all the matches.  This is called
109 @dfn{globbing}.
110
111 You could do this using @code{fnmatch}, by reading the directory entries
112 one by one and testing each one with @code{fnmatch}.  But that would be
113 slow (and complex, since you would have to handle subdirectories by
114 hand).
115
116 The library provides a function @code{glob} to make this particular use
117 of wildcards convenient.  @code{glob} and the other symbols in this
118 section are declared in @file{glob.h}.
119
120 @menu
121 * Calling Glob::             Basic use of @code{glob}.
122 * Flags for Globbing::       Flags that enable various options in @code{glob}.
123 * More Flags for Globbing::  GNU specific extensions to @code{glob}.
124 @end menu
125
126 @node Calling Glob
127 @subsection Calling @code{glob}
128
129 The result of globbing is a vector of file names (strings).  To return
130 this vector, @code{glob} uses a special data type, @code{glob_t}, which
131 is a structure.  You pass @code{glob} the address of the structure, and
132 it fills in the structure's fields to tell you about the results.
133
134 @comment glob.h
135 @comment POSIX.2
136 @deftp {Data Type} glob_t
137 This data type holds a pointer to a word vector.  More precisely, it
138 records both the address of the word vector and its size.  The GNU
139 implementation contains some more fields which are non-standard
140 extensions.
141
142 @table @code
143 @item gl_pathc
144 The number of elements in the vector.
145
146 @item gl_pathv
147 The address of the vector.  This field has type @w{@code{char **}}.
148
149 @item gl_offs
150 The offset of the first real element of the vector, from its nominal
151 address in the @code{gl_pathv} field.  Unlike the other fields, this
152 is always an input to @code{glob}, rather than an output from it.
153
154 If you use a nonzero offset, then that many elements at the beginning of
155 the vector are left empty.  (The @code{glob} function fills them with
156 null pointers.)
157
158 The @code{gl_offs} field is meaningful only if you use the
159 @code{GLOB_DOOFFS} flag.  Otherwise, the offset is always zero
160 regardless of what is in this field, and the first real element comes at
161 the beginning of the vector.
162
163 @item gl_closedir
164 The address of an alternative implementation of the @code{closedir}
165 function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in
166 the flag parameter.  The type of this field is
167 @w{@code{void (*) (void *)}}.
168
169 This is a GNU extension.
170
171 @item gl_readdir
172 The address of an alternative implementation of the @code{readdir}
173 function used to read the contents of a directory.  It is used if the
174 @code{GLOB_ALTDIRFUNC} bit is set in the flag parameter.  The type of
175 this field is @w{@code{struct dirent *(*) (void *)}}.
176
177 This is a GNU extension.
178
179 @item gl_opendir
180 The address of an alternative implementation of the @code{opendir}
181 function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in
182 the flag parameter.  The type of this field is
183 @w{@code{void *(*) (const char *)}}.
184
185 This is a GNU extension.
186
187 @item gl_stat
188 The address of an alternative implementation of the @code{stat} function
189 to get information about an object in the filesystem.  It is used if the
190 @code{GLOB_ALTDIRFUNC} bit is set in the flag parameter.  The type of
191 this field is @w{@code{int (*) (const char *, struct stat *)}}.
192
193 This is a GNU extension.
194
195 @item gl_lstat
196 The address of an alternative implementation of the @code{lstat}
197 function to get information about an object in the filesystems, not
198 following symbolic links.  It is used if the @code{GLOB_ALTDIRFUNC} bit
199 is set in the flag parameter.  The type of this field is @w{@code{int
200 (*) (const char *, struct stat *)}}.
201
202 This is a GNU extension.
203 @end table
204 @end deftp
205
206 @comment glob.h
207 @comment POSIX.2
208 @deftypefun int glob (const char *@var{pattern}, int @var{flags}, int (*@var{errfunc}) (const char *@var{filename}, int @var{error-code}), glob_t *@var{vector-ptr})
209 The function @code{glob} does globbing using the pattern @var{pattern}
210 in the current directory.  It puts the result in a newly allocated
211 vector, and stores the size and address of this vector into
212 @code{*@var{vector-ptr}}.  The argument @var{flags} is a combination of
213 bit flags; see @ref{Flags for Globbing}, for details of the flags.
214
215 The result of globbing is a sequence of file names.  The function
216 @code{glob} allocates a string for each resulting word, then
217 allocates a vector of type @code{char **} to store the addresses of
218 these strings.  The last element of the vector is a null pointer.
219 This vector is called the @dfn{word vector}.
220
221 To return this vector, @code{glob} stores both its address and its
222 length (number of elements, not counting the terminating null pointer)
223 into @code{*@var{vector-ptr}}.
224
225 Normally, @code{glob} sorts the file names alphabetically before
226 returning them.  You can turn this off with the flag @code{GLOB_NOSORT}
227 if you want to get the information as fast as possible.  Usually it's
228 a good idea to let @code{glob} sort them---if you process the files in
229 alphabetical order, the users will have a feel for the rate of progress
230 that your application is making.
231
232 If @code{glob} succeeds, it returns 0.  Otherwise, it returns one
233 of these error codes:
234
235 @table @code
236 @comment glob.h
237 @comment POSIX.2
238 @item GLOB_ABORTED
239 There was an error opening a directory, and you used the flag
240 @code{GLOB_ERR} or your specified @var{errfunc} returned a nonzero
241 value.
242 @iftex
243 See below
244 @end iftex
245 @ifinfo
246 @xref{Flags for Globbing},
247 @end ifinfo
248 for an explanation of the @code{GLOB_ERR} flag and @var{errfunc}.
249
250 @comment glob.h
251 @comment POSIX.2
252 @item GLOB_NOMATCH
253 The pattern didn't match any existing files.  If you use the
254 @code{GLOB_NOCHECK} flag, then you never get this error code, because
255 that flag tells @code{glob} to @emph{pretend} that the pattern matched
256 at least one file.
257
258 @comment glob.h
259 @comment POSIX.2
260 @item GLOB_NOSPACE
261 It was impossible to allocate memory to hold the result.
262 @end table
263
264 In the event of an error, @code{glob} stores information in
265 @code{*@var{vector-ptr}} about all the matches it has found so far.
266 @end deftypefun
267
268 @node Flags for Globbing
269 @subsection Flags for Globbing
270
271 This section describes the flags that you can specify in the
272 @var{flags} argument to @code{glob}.  Choose the flags you want,
273 and combine them with the C bitwise OR operator @code{|}.
274
275 @table @code
276 @comment glob.h
277 @comment POSIX.2
278 @item GLOB_APPEND
279 Append the words from this expansion to the vector of words produced by
280 previous calls to @code{glob}.  This way you can effectively expand
281 several words as if they were concatenated with spaces between them.
282
283 In order for appending to work, you must not modify the contents of the
284 word vector structure between calls to @code{glob}.  And, if you set
285 @code{GLOB_DOOFFS} in the first call to @code{glob}, you must also
286 set it when you append to the results.
287
288 Note that the pointer stored in @code{gl_pathv} may no longer be valid
289 after you call @code{glob} the second time, because @code{glob} might
290 have relocated the vector.  So always fetch @code{gl_pathv} from the
291 @code{glob_t} structure after each @code{glob} call; @strong{never} save
292 the pointer across calls.
293
294 @comment glob.h
295 @comment POSIX.2
296 @item GLOB_DOOFFS
297 Leave blank slots at the beginning of the vector of words.
298 The @code{gl_offs} field says how many slots to leave.
299 The blank slots contain null pointers.
300
301 @comment glob.h
302 @comment POSIX.2
303 @item GLOB_ERR
304 Give up right away and report an error if there is any difficulty
305 reading the directories that must be read in order to expand @var{pattern}
306 fully.  Such difficulties might include a directory in which you don't
307 have the requisite access.  Normally, @code{glob} tries its best to keep
308 on going despite any errors, reading whatever directories it can.
309
310 You can exercise even more control than this by specifying an
311 error-handler function @var{errfunc} when you call @code{glob}.  If
312 @var{errfunc} is not a null pointer, then @code{glob} doesn't give up
313 right away when it can't read a directory; instead, it calls
314 @var{errfunc} with two arguments, like this:
315
316 @smallexample
317 (*@var{errfunc}) (@var{filename}, @var{error-code})
318 @end smallexample
319
320 @noindent
321 The argument @var{filename} is the name of the directory that
322 @code{glob} couldn't open or couldn't read, and @var{error-code} is the
323 @code{errno} value that was reported to @code{glob}.
324
325 If the error handler function returns nonzero, then @code{glob} gives up
326 right away.  Otherwise, it continues.
327
328 @comment glob.h
329 @comment POSIX.2
330 @item GLOB_MARK
331 If the pattern matches the name of a directory, append @samp{/} to the
332 directory's name when returning it.
333
334 @comment glob.h
335 @comment POSIX.2
336 @item GLOB_NOCHECK
337 If the pattern doesn't match any file names, return the pattern itself
338 as if it were a file name that had been matched.  (Normally, when the
339 pattern doesn't match anything, @code{glob} returns that there were no
340 matches.)
341
342 @comment glob.h
343 @comment POSIX.2
344 @item GLOB_NOSORT
345 Don't sort the file names; return them in no particular order.
346 (In practice, the order will depend on the order of the entries in
347 the directory.)  The only reason @emph{not} to sort is to save time.
348
349 @comment glob.h
350 @comment POSIX.2
351 @item GLOB_NOESCAPE
352 Don't treat the @samp{\} character specially in patterns.  Normally,
353 @samp{\} quotes the following character, turning off its special meaning
354 (if any) so that it matches only itself.  When quoting is enabled, the
355 pattern @samp{\?} matches only the string @samp{?}, because the question
356 mark in the pattern acts like an ordinary character.
357
358 If you use @code{GLOB_NOESCAPE}, then @samp{\} is an ordinary character.
359
360 @code{glob} does its work by calling the function @code{fnmatch}
361 repeatedly.  It handles the flag @code{GLOB_NOESCAPE} by turning on the
362 @code{FNM_NOESCAPE} flag in calls to @code{fnmatch}.
363 @end table
364
365 @node More Flags for Globbing
366 @subsection More Flags for Globbing
367
368 Beside the flags described in the last section, the GNU implementation of
369 @code{glob} allows a few more flags which are also defined in the
370 @file{glob.h} file.  Some of the extensions implement functionality
371 which is available in modern shell implementations.
372
373 @table @code
374 @comment glob.h
375 @comment GNU
376 @item GLOB_PERIOD
377 The @code{.} character (period) is treated special.  It cannot be
378 matched by wildcards.  @xref{Wildcard Matching}, @code{FNM_PERIOD}.
379
380 @comment glob.h
381 @comment GNU
382 @item GLOB_MAGCHAR
383 The @code{GLOB_MAGCHAR} value is not to be given to @code{glob} in the
384 @var{flags} parameter.  Instead, @code{glob} sets this bit in the
385 @var{gl_flags} element of the @var{glob_t} structure provided as the
386 result if the pattern used for matching contains any wildcard character.
387
388 @comment glob.h
389 @comment GNU
390 @item GLOB_ALTDIRFUNC
391 Instead of the using the using the normal functions for accessing the
392 filesystem the @code{glob} implementation uses the user-supplied
393 functions specified in the structure pointed to by @var{pglob}
394 parameter.  For more information about the functions refer to the
395 sections about directory handling @ref{Accessing Directories} and
396 @ref{Reading Attributes}.
397
398 @comment glob.h
399 @comment GNU
400 @item GLOB_BRACE
401 If this flag is given the handling of braces in the pattern is changed.
402 It is now required that braces appear correctly grouped.  I.e., for each
403 opening brace there must be a closing one.  Braces can be used
404 recursively.  So it is possible to define one brace expression in
405 another one.  It is important to note that the range of each brace
406 expression is completely contained in the outer brace expression (if
407 there is one).
408
409 The string between the matching braces is separated into single
410 expressions by splitting at @code{,} (comma) characters.  The commas
411 themself are discarded.  Please note what we said above about recursive
412 brace expressions.  The commas used to separate the subexpressions must
413 be at the same level.  Commas in brace subexpressions are not matched.
414 They are used during expansion of the brace expression of the deeper
415 level.  The example below shows this
416
417 @smallexample
418 glob ("@{foo/@{,bar,biz@},baz@}", GLOB_BRACE, NULL, &result)
419 @end smallexample
420
421 @noindent
422 is equivalent to the sequence
423
424 @smallexample
425 glob ("foo/", GLOB_BRACE, NULL, &result)
426 glob ("foo/bar", GLOB_BRACE|GLOB_APPEND, NULL, &result)
427 glob ("foo/biz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
428 glob ("baz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
429 @end smallexample
430
431 @noindent
432 if we leave aside error handling.
433
434 @comment glob.h
435 @comment GNU
436 @item GLOB_NOMAGIC
437 If the pattern contains no wildcard constructs (it is a literal file name),
438 return it as the sole ``matching'' word, even if no file exists by that name.
439
440 @comment glob.h
441 @comment GNU
442 @item GLOB_TILDE
443 If this flag is used the character @code{~} (tilde) is handled special
444 if it appears at the beginning of the pattern.  Instead of being taken
445 verbatim it is used to represent the home directory of a known user.
446
447 If @code{~} is the only character in pattern or it is followed by a
448 @code{/} (slash), the home directory of the process owner is
449 substituted.  Using @code{getlogin} and @code{getpwnam} the information
450 is read from the system databases.  As an example take user @code{bart}
451 with his home directory at @file{/home/bart}.  For him a call like
452
453 @smallexample
454 glob ("~/bin/*", GLOB_TILDE, NULL, &result)
455 @end smallexample
456
457 @noindent
458 would return the contents of the directory @file{/home/bart/bin}.
459 Instead of referring to the own home directory it is also possible to
460 name the home directory of other users.  To do so one has to append the
461 user name after the tilde character.  So the contents of user
462 @code{homer}'s @file{bin} directory can be retrieved by
463
464 @smallexample
465 glob ("~homer/bin/*", GLOB_TILDE, NULL, &result)
466 @end smallexample
467
468 This functionality is equivalent to what is available in C-shells.
469
470 @comment glob.h
471 @comment GNU
472 @item GLOB_ONLYDIR
473 If this flag is used the globbing function takes this as a
474 @strong{hint} that the caller is only interested in directories
475 matching the pattern.  If the information about the type of the file
476 is easily available non-directories will be rejected but no extra
477 work will be done to determine the information for each file.  I.e.,
478 the caller must still be able to filter directories out.
479
480 This functionality is only available witht eh GNU @code{glob}
481 implementation.  It is mainly used internally to increase the
482 performance but might be useful for a user as well and therefore is
483 documented here.
484 @end table
485
486 Calling @code{glob} will in most cases allocate resources which are used
487 to represent the result of the function call.  If the same object of
488 type @code{glob_t} is used in multiple call to @code{glob} the resources
489 are freed or reused so that no leaks appear.  But this does not include
490 the time when all @code{glob} calls are done.
491
492 @comment glob.h
493 @comment POSIX.2
494 @deftypefun void globfree (glob_t *@var{pglob})
495 The @code{globfree} function frees all resources allocated by previous
496 calls to @code{glob} associated with the object pointed to by
497 @var{pglob}.  This function should be called whenever the currently used
498 @code{glob_t} typed object isn't used anymore.
499 @end deftypefun
500
501
502 @node Regular Expressions
503 @section Regular Expression Matching
504
505 The GNU C library supports two interfaces for matching regular
506 expressions.  One is the standard POSIX.2 interface, and the other is
507 what the GNU system has had for many years.
508
509 Both interfaces are declared in the header file @file{regex.h}.
510 If you define @w{@code{_POSIX_C_SOURCE}}, then only the POSIX.2
511 functions, structures, and constants are declared.
512 @c !!! we only document the POSIX.2 interface here!!
513
514 @menu
515 * POSIX Regexp Compilation::    Using @code{regcomp} to prepare to match.
516 * Flags for POSIX Regexps::     Syntax variations for @code{regcomp}.
517 * Matching POSIX Regexps::      Using @code{regexec} to match the compiled
518                                    pattern that you get from @code{regcomp}.
519 * Regexp Subexpressions::       Finding which parts of the string were matched.
520 * Subexpression Complications:: Find points of which parts were matched.
521 * Regexp Cleanup::              Freeing storage; reporting errors.
522 @end menu
523
524 @node POSIX Regexp Compilation
525 @subsection POSIX Regular Expression Compilation
526
527 Before you can actually match a regular expression, you must
528 @dfn{compile} it.  This is not true compilation---it produces a special
529 data structure, not machine instructions.  But it is like ordinary
530 compilation in that its purpose is to enable you to ``execute'' the
531 pattern fast.  (@xref{Matching POSIX Regexps}, for how to use the
532 compiled regular expression for matching.)
533
534 There is a special data type for compiled regular expressions:
535
536 @comment regex.h
537 @comment POSIX.2
538 @deftp {Data Type} regex_t
539 This type of object holds a compiled regular expression.
540 It is actually a structure.  It has just one field that your programs
541 should look at:
542
543 @table @code
544 @item re_nsub
545 This field holds the number of parenthetical subexpressions in the
546 regular expression that was compiled.
547 @end table
548
549 There are several other fields, but we don't describe them here, because
550 only the functions in the library should use them.
551 @end deftp
552
553 After you create a @code{regex_t} object, you can compile a regular
554 expression into it by calling @code{regcomp}.
555
556 @comment regex.h
557 @comment POSIX.2
558 @deftypefun int regcomp (regex_t *@var{compiled}, const char *@var{pattern}, int @var{cflags})
559 The function @code{regcomp} ``compiles'' a regular expression into a
560 data structure that you can use with @code{regexec} to match against a
561 string.  The compiled regular expression format is designed for
562 efficient matching.  @code{regcomp} stores it into @code{*@var{compiled}}.
563
564 It's up to you to allocate an object of type @code{regex_t} and pass its
565 address to @code{regcomp}.
566
567 The argument @var{cflags} lets you specify various options that control
568 the syntax and semantics of regular expressions.  @xref{Flags for POSIX
569 Regexps}.
570
571 If you use the flag @code{REG_NOSUB}, then @code{regcomp} omits from
572 the compiled regular expression the information necessary to record
573 how subexpressions actually match.  In this case, you might as well
574 pass @code{0} for the @var{matchptr} and @var{nmatch} arguments when
575 you call @code{regexec}.
576
577 If you don't use @code{REG_NOSUB}, then the compiled regular expression
578 does have the capacity to record how subexpressions match.  Also,
579 @code{regcomp} tells you how many subexpressions @var{pattern} has, by
580 storing the number in @code{@var{compiled}->re_nsub}.  You can use that
581 value to decide how long an array to allocate to hold information about
582 subexpression matches.
583
584 @code{regcomp} returns @code{0} if it succeeds in compiling the regular
585 expression; otherwise, it returns a nonzero error code (see the table
586 below).  You can use @code{regerror} to produce an error message string
587 describing the reason for a nonzero value; see @ref{Regexp Cleanup}.
588
589 @end deftypefun
590
591 Here are the possible nonzero values that @code{regcomp} can return:
592
593 @table @code
594 @comment regex.h
595 @comment POSIX.2
596 @item REG_BADBR
597 There was an invalid @samp{\@{@dots{}\@}} construct in the regular
598 expression.  A valid @samp{\@{@dots{}\@}} construct must contain either
599 a single number, or two numbers in increasing order separated by a
600 comma.
601
602 @comment regex.h
603 @comment POSIX.2
604 @item REG_BADPAT
605 There was a syntax error in the regular expression.
606
607 @comment regex.h
608 @comment POSIX.2
609 @item REG_BADRPT
610 A repetition operator such as @samp{?} or @samp{*} appeared in a bad
611 position (with no preceding subexpression to act on).
612
613 @comment regex.h
614 @comment POSIX.2
615 @item REG_ECOLLATE
616 The regular expression referred to an invalid collating element (one not
617 defined in the current locale for string collation).  @xref{Locale
618 Categories}.
619
620 @comment regex.h
621 @comment POSIX.2
622 @item REG_ECTYPE
623 The regular expression referred to an invalid character class name.
624
625 @comment regex.h
626 @comment POSIX.2
627 @item REG_EESCAPE
628 The regular expression ended with @samp{\}.
629
630 @comment regex.h
631 @comment POSIX.2
632 @item REG_ESUBREG
633 There was an invalid number in the @samp{\@var{digit}} construct.
634
635 @comment regex.h
636 @comment POSIX.2
637 @item REG_EBRACK
638 There were unbalanced square brackets in the regular expression.
639
640 @comment regex.h
641 @comment POSIX.2
642 @item REG_EPAREN
643 An extended regular expression had unbalanced parentheses,
644 or a basic regular expression had unbalanced @samp{\(} and @samp{\)}.
645
646 @comment regex.h
647 @comment POSIX.2
648 @item REG_EBRACE
649 The regular expression had unbalanced @samp{\@{} and @samp{\@}}.
650
651 @comment regex.h
652 @comment POSIX.2
653 @item REG_ERANGE
654 One of the endpoints in a range expression was invalid.
655
656 @comment regex.h
657 @comment POSIX.2
658 @item REG_ESPACE
659 @code{regcomp} ran out of memory.
660 @end table
661
662 @node Flags for POSIX Regexps
663 @subsection Flags for POSIX Regular Expressions
664
665 These are the bit flags that you can use in the @var{cflags} operand when
666 compiling a regular expression with @code{regcomp}.
667
668 @table @code
669 @comment regex.h
670 @comment POSIX.2
671 @item REG_EXTENDED
672 Treat the pattern as an extended regular expression, rather than as a
673 basic regular expression.
674
675 @comment regex.h
676 @comment POSIX.2
677 @item REG_ICASE
678 Ignore case when matching letters.
679
680 @comment regex.h
681 @comment POSIX.2
682 @item REG_NOSUB
683 Don't bother storing the contents of the @var{matches-ptr} array.
684
685 @comment regex.h
686 @comment POSIX.2
687 @item REG_NEWLINE
688 Treat a newline in @var{string} as dividing @var{string} into multiple
689 lines, so that @samp{$} can match before the newline and @samp{^} can
690 match after.  Also, don't permit @samp{.} to match a newline, and don't
691 permit @samp{[^@dots{}]} to match a newline.
692
693 Otherwise, newline acts like any other ordinary character.
694 @end table
695
696 @node Matching POSIX Regexps
697 @subsection Matching a Compiled POSIX Regular Expression
698
699 Once you have compiled a regular expression, as described in @ref{POSIX
700 Regexp Compilation}, you can match it against strings using
701 @code{regexec}.  A match anywhere inside the string counts as success,
702 unless the regular expression contains anchor characters (@samp{^} or
703 @samp{$}).
704
705 @comment regex.h
706 @comment POSIX.2
707 @deftypefun int regexec (regex_t *@var{compiled}, char *@var{string}, size_t @var{nmatch}, regmatch_t @var{matchptr} @t{[]}, int @var{eflags})
708 This function tries to match the compiled regular expression
709 @code{*@var{compiled}} against @var{string}.
710
711 @code{regexec} returns @code{0} if the regular expression matches;
712 otherwise, it returns a nonzero value.  See the table below for
713 what nonzero values mean.  You can use @code{regerror} to produce an
714 error message string describing the reason for a nonzero value;
715 see @ref{Regexp Cleanup}.
716
717 The argument @var{eflags} is a word of bit flags that enable various
718 options.
719
720 If you want to get information about what part of @var{string} actually
721 matched the regular expression or its subexpressions, use the arguments
722 @var{matchptr} and @var{nmatch}.  Otherwise, pass @code{0} for
723 @var{nmatch}, and @code{NULL} for @var{matchptr}.  @xref{Regexp
724 Subexpressions}.
725 @end deftypefun
726
727 You must match the regular expression with the same set of current
728 locales that were in effect when you compiled the regular expression.
729
730 The function @code{regexec} accepts the following flags in the
731 @var{eflags} argument:
732
733 @table @code
734 @comment regex.h
735 @comment POSIX.2
736 @item REG_NOTBOL
737 Do not regard the beginning of the specified string as the beginning of
738 a line; more generally, don't make any assumptions about what text might
739 precede it.
740
741 @comment regex.h
742 @comment POSIX.2
743 @item REG_NOTEOL
744 Do not regard the end of the specified string as the end of a line; more
745 generally, don't make any assumptions about what text might follow it.
746 @end table
747
748 Here are the possible nonzero values that @code{regexec} can return:
749
750 @table @code
751 @comment regex.h
752 @comment POSIX.2
753 @item REG_NOMATCH
754 The pattern didn't match the string.  This isn't really an error.
755
756 @comment regex.h
757 @comment POSIX.2
758 @item REG_ESPACE
759 @code{regexec} ran out of memory.
760 @end table
761
762 @node Regexp Subexpressions
763 @subsection Match Results with Subexpressions
764
765 When @code{regexec} matches parenthetical subexpressions of
766 @var{pattern}, it records which parts of @var{string} they match.  It
767 returns that information by storing the offsets into an array whose
768 elements are structures of type @code{regmatch_t}.  The first element of
769 the array (index @code{0}) records the part of the string that matched
770 the entire regular expression.  Each other element of the array records
771 the beginning and end of the part that matched a single parenthetical
772 subexpression.
773
774 @comment regex.h
775 @comment POSIX.2
776 @deftp {Data Type} regmatch_t
777 This is the data type of the @var{matcharray} array that you pass to
778 @code{regexec}.  It contains two structure fields, as follows:
779
780 @table @code
781 @item rm_so
782 The offset in @var{string} of the beginning of a substring.  Add this
783 value to @var{string} to get the address of that part.
784
785 @item rm_eo
786 The offset in @var{string} of the end of the substring.
787 @end table
788 @end deftp
789
790 @comment regex.h
791 @comment POSIX.2
792 @deftp {Data Type} regoff_t
793 @code{regoff_t} is an alias for another signed integer type.
794 The fields of @code{regmatch_t} have type @code{regoff_t}.
795 @end deftp
796
797 The @code{regmatch_t} elements correspond to subexpressions
798 positionally; the first element (index @code{1}) records where the first
799 subexpression matched, the second element records the second
800 subexpression, and so on.  The order of the subexpressions is the order
801 in which they begin.
802
803 When you call @code{regexec}, you specify how long the @var{matchptr}
804 array is, with the @var{nmatch} argument.  This tells @code{regexec} how
805 many elements to store.  If the actual regular expression has more than
806 @var{nmatch} subexpressions, then you won't get offset information about
807 the rest of them.  But this doesn't alter whether the pattern matches a
808 particular string or not.
809
810 If you don't want @code{regexec} to return any information about where
811 the subexpressions matched, you can either supply @code{0} for
812 @var{nmatch}, or use the flag @code{REG_NOSUB} when you compile the
813 pattern with @code{regcomp}.
814
815 @node Subexpression Complications
816 @subsection Complications in Subexpression Matching
817
818 Sometimes a subexpression matches a substring of no characters.  This
819 happens when @samp{f\(o*\)} matches the string @samp{fum}.  (It really
820 matches just the @samp{f}.)  In this case, both of the offsets identify
821 the point in the string where the null substring was found.  In this
822 example, the offsets are both @code{1}.
823
824 Sometimes the entire regular expression can match without using some of
825 its subexpressions at all---for example, when @samp{ba\(na\)*} matches the
826 string @samp{ba}, the parenthetical subexpression is not used.  When
827 this happens, @code{regexec} stores @code{-1} in both fields of the
828 element for that subexpression.
829
830 Sometimes matching the entire regular expression can match a particular
831 subexpression more than once---for example, when @samp{ba\(na\)*}
832 matches the string @samp{bananana}, the parenthetical subexpression
833 matches three times.  When this happens, @code{regexec} usually stores
834 the offsets of the last part of the string that matched the
835 subexpression.  In the case of @samp{bananana}, these offsets are
836 @code{6} and @code{8}.
837
838 But the last match is not always the one that is chosen.  It's more
839 accurate to say that the last @emph{opportunity} to match is the one
840 that takes precedence.  What this means is that when one subexpression
841 appears within another, then the results reported for the inner
842 subexpression reflect whatever happened on the last match of the outer
843 subexpression.  For an example, consider @samp{\(ba\(na\)*s \)*} matching
844 the string @samp{bananas bas }.  The last time the inner expression
845 actually matches is near the end of the first word.  But it is
846 @emph{considered} again in the second word, and fails to match there.
847 @code{regexec} reports nonuse of the ``na'' subexpression.
848
849 Another place where this rule applies is when the regular expression
850 @w{@samp{\(ba\(na\)*s \|nefer\(ti\)* \)*}} matches @samp{bananas nefertiti}.
851 The ``na'' subexpression does match in the first word, but it doesn't
852 match in the second word because the other alternative is used there.
853 Once again, the second repetition of the outer subexpression overrides
854 the first, and within that second repetition, the ``na'' subexpression
855 is not used.  So @code{regexec} reports nonuse of the ``na''
856 subexpression.
857
858 @node Regexp Cleanup
859 @subsection POSIX Regexp Matching Cleanup
860
861 When you are finished using a compiled regular expression, you can
862 free the storage it uses by calling @code{regfree}.
863
864 @comment regex.h
865 @comment POSIX.2
866 @deftypefun void regfree (regex_t *@var{compiled})
867 Calling @code{regfree} frees all the storage that @code{*@var{compiled}}
868 points to.  This includes various internal fields of the @code{regex_t}
869 structure that aren't documented in this manual.
870
871 @code{regfree} does not free the object @code{*@var{compiled}} itself.
872 @end deftypefun
873
874 You should always free the space in a @code{regex_t} structure with
875 @code{regfree} before using the structure to compile another regular
876 expression.
877
878 When @code{regcomp} or @code{regexec} reports an error, you can use
879 the function @code{regerror} to turn it into an error message string.
880
881 @comment regex.h
882 @comment POSIX.2
883 @deftypefun size_t regerror (int @var{errcode}, regex_t *@var{compiled}, char *@var{buffer}, size_t @var{length})
884 This function produces an error message string for the error code
885 @var{errcode}, and stores the string in @var{length} bytes of memory
886 starting at @var{buffer}.  For the @var{compiled} argument, supply the
887 same compiled regular expression structure that @code{regcomp} or
888 @code{regexec} was working with when it got the error.  Alternatively,
889 you can supply @code{NULL} for @var{compiled}; you will still get a
890 meaningful error message, but it might not be as detailed.
891
892 If the error message can't fit in @var{length} bytes (including a
893 terminating null character), then @code{regerror} truncates it.
894 The string that @code{regerror} stores is always null-terminated
895 even if it has been truncated.
896
897 The return value of @code{regerror} is the minimum length needed to
898 store the entire error message.  If this is less than @var{length}, then
899 the error message was not truncated, and you can use it.  Otherwise, you
900 should call @code{regerror} again with a larger buffer.
901
902 Here is a function which uses @code{regerror}, but always dynamically
903 allocates a buffer for the error message:
904
905 @smallexample
906 char *get_regerror (int errcode, regex_t *compiled)
907 @{
908   size_t length = regerror (errcode, compiled, NULL, 0);
909   char *buffer = xmalloc (length);
910   (void) regerror (errcode, compiled, buffer, length);
911   return buffer;
912 @}
913 @end smallexample
914 @end deftypefun
915
916 @c !!!! this is not actually in the library....
917 @node Word Expansion
918 @section Shell-Style Word Expansion
919 @cindex word expansion
920 @cindex expansion of shell words
921
922 @dfn{Word expansion} means the process of splitting a string into
923 @dfn{words} and substituting for variables, commands, and wildcards
924 just as the shell does.
925
926 For example, when you write @samp{ls -l foo.c}, this string is split
927 into three separate words---@samp{ls}, @samp{-l} and @samp{foo.c}.
928 This is the most basic function of word expansion.
929
930 When you write @samp{ls *.c}, this can become many words, because
931 the word @samp{*.c} can be replaced with any number of file names.
932 This is called @dfn{wildcard expansion}, and it is also a part of
933 word expansion.
934
935 When you use @samp{echo $PATH} to print your path, you are taking
936 advantage of @dfn{variable substitution}, which is also part of word
937 expansion.
938
939 Ordinary programs can perform word expansion just like the shell by
940 calling the library function @code{wordexp}.
941
942 @menu
943 * Expansion Stages::    What word expansion does to a string.
944 * Calling Wordexp::     How to call @code{wordexp}.
945 * Flags for Wordexp::   Options you can enable in @code{wordexp}.
946 * Wordexp Example::     A sample program that does word expansion.
947 @end menu
948
949 @node Expansion Stages
950 @subsection The Stages of Word Expansion
951
952 When word expansion is applied to a sequence of words, it performs the
953 following transformations in the order shown here:
954
955 @enumerate
956 @item
957 @cindex tilde expansion
958 @dfn{Tilde expansion}: Replacement of @samp{~foo} with the name of
959 the home directory of @samp{foo}.
960
961 @item
962 Next, three different transformations are applied in the same step,
963 from left to right:
964
965 @itemize @bullet
966 @item
967 @cindex variable substitution
968 @cindex substitution of variables and commands
969 @dfn{Variable substitution}: Environment variables are substituted for
970 references such as @samp{$foo}.
971
972 @item
973 @cindex command substitution
974 @dfn{Command substitution}: Constructs such as @w{@samp{`cat foo`}} and
975 the equivalent @w{@samp{$(cat foo)}} are replaced with the output from
976 the inner command.
977
978 @item
979 @cindex arithmetic expansion
980 @dfn{Arithmetic expansion}: Constructs such as @samp{$(($x-1))} are
981 replaced with the result of the arithmetic computation.
982 @end itemize
983
984 @item
985 @cindex field splitting
986 @dfn{Field splitting}: subdivision of the text into @dfn{words}.
987
988 @item
989 @cindex wildcard expansion
990 @dfn{Wildcard expansion}: The replacement of a construct such as @samp{*.c}
991 with a list of @samp{.c} file names.  Wildcard expansion applies to an
992 entire word at a time, and replaces that word with 0 or more file names
993 that are themselves words.
994
995 @item
996 @cindex quote removal
997 @cindex removal of quotes
998 @dfn{Quote removal}: The deletion of string-quotes, now that they have
999 done their job by inhibiting the above transformations when appropriate.
1000 @end enumerate
1001
1002 For the details of these transformations, and how to write the constructs
1003 that use them, see @w{@cite{The BASH Manual}} (to appear).
1004
1005 @node Calling Wordexp
1006 @subsection Calling @code{wordexp}
1007
1008 All the functions, constants and data types for word expansion are
1009 declared in the header file @file{wordexp.h}.
1010
1011 Word expansion produces a vector of words (strings).  To return this
1012 vector, @code{wordexp} uses a special data type, @code{wordexp_t}, which
1013 is a structure.  You pass @code{wordexp} the address of the structure,
1014 and it fills in the structure's fields to tell you about the results.
1015
1016 @comment wordexp.h
1017 @comment POSIX.2
1018 @deftp {Data Type} {wordexp_t}
1019 This data type holds a pointer to a word vector.  More precisely, it
1020 records both the address of the word vector and its size.
1021
1022 @table @code
1023 @item we_wordc
1024 The number of elements in the vector.
1025
1026 @item we_wordv
1027 The address of the vector.  This field has type @w{@code{char **}}.
1028
1029 @item we_offs
1030 The offset of the first real element of the vector, from its nominal
1031 address in the @code{we_wordv} field.  Unlike the other fields, this
1032 is always an input to @code{wordexp}, rather than an output from it.
1033
1034 If you use a nonzero offset, then that many elements at the beginning of
1035 the vector are left empty.  (The @code{wordexp} function fills them with
1036 null pointers.)
1037
1038 The @code{we_offs} field is meaningful only if you use the
1039 @code{WRDE_DOOFFS} flag.  Otherwise, the offset is always zero
1040 regardless of what is in this field, and the first real element comes at
1041 the beginning of the vector.
1042 @end table
1043 @end deftp
1044
1045 @comment wordexp.h
1046 @comment POSIX.2
1047 @deftypefun int wordexp (const char *@var{words}, wordexp_t *@var{word-vector-ptr}, int @var{flags})
1048 Perform word expansion on the string @var{words}, putting the result in
1049 a newly allocated vector, and store the size and address of this vector
1050 into @code{*@var{word-vector-ptr}}.  The argument @var{flags} is a
1051 combination of bit flags; see @ref{Flags for Wordexp}, for details of
1052 the flags.
1053
1054 You shouldn't use any of the characters @samp{|&;<>} in the string
1055 @var{words} unless they are quoted; likewise for newline.  If you use
1056 these characters unquoted, you will get the @code{WRDE_BADCHAR} error
1057 code.  Don't use parentheses or braces unless they are quoted or part of
1058 a word expansion construct.  If you use quotation characters @samp{'"`},
1059 they should come in pairs that balance.
1060
1061 The results of word expansion are a sequence of words.  The function
1062 @code{wordexp} allocates a string for each resulting word, then
1063 allocates a vector of type @code{char **} to store the addresses of
1064 these strings.  The last element of the vector is a null pointer.
1065 This vector is called the @dfn{word vector}.
1066
1067 To return this vector, @code{wordexp} stores both its address and its
1068 length (number of elements, not counting the terminating null pointer)
1069 into @code{*@var{word-vector-ptr}}.
1070
1071 If @code{wordexp} succeeds, it returns 0.  Otherwise, it returns one
1072 of these error codes:
1073
1074 @table @code
1075 @comment wordexp.h
1076 @comment POSIX.2
1077 @item WRDE_BADCHAR
1078 The input string @var{words} contains an unquoted invalid character such
1079 as @samp{|}.
1080
1081 @comment wordexp.h
1082 @comment POSIX.2
1083 @item WRDE_BADVAL
1084 The input string refers to an undefined shell variable, and you used the flag
1085 @code{WRDE_UNDEF} to forbid such references.
1086
1087 @comment wordexp.h
1088 @comment POSIX.2
1089 @item WRDE_CMDSUB
1090 The input string uses command substitution, and you used the flag
1091 @code{WRDE_NOCMD} to forbid command substitution.
1092
1093 @comment wordexp.h
1094 @comment POSIX.2
1095 @item WRDE_NOSPACE
1096 It was impossible to allocate memory to hold the result.  In this case,
1097 @code{wordexp} can store part of the results---as much as it could
1098 allocate room for.
1099
1100 @comment wordexp.h
1101 @comment POSIX.2
1102 @item WRDE_SYNTAX
1103 There was a syntax error in the input string.  For example, an unmatched
1104 quoting character is a syntax error.
1105 @end table
1106 @end deftypefun
1107
1108 @comment wordexp.h
1109 @comment POSIX.2
1110 @deftypefun void wordfree (wordexp_t *@var{word-vector-ptr})
1111 Free the storage used for the word-strings and vector that
1112 @code{*@var{word-vector-ptr}} points to.  This does not free the
1113 structure @code{*@var{word-vector-ptr}} itself---only the other
1114 data it points to.
1115 @end deftypefun
1116
1117 @node Flags for Wordexp
1118 @subsection Flags for Word Expansion
1119
1120 This section describes the flags that you can specify in the
1121 @var{flags} argument to @code{wordexp}.  Choose the flags you want,
1122 and combine them with the C operator @code{|}.
1123
1124 @table @code
1125 @comment wordexp.h
1126 @comment POSIX.2
1127 @item WRDE_APPEND
1128 Append the words from this expansion to the vector of words produced by
1129 previous calls to @code{wordexp}.  This way you can effectively expand
1130 several words as if they were concatenated with spaces between them.
1131
1132 In order for appending to work, you must not modify the contents of the
1133 word vector structure between calls to @code{wordexp}.  And, if you set
1134 @code{WRDE_DOOFFS} in the first call to @code{wordexp}, you must also
1135 set it when you append to the results.
1136
1137 @comment wordexp.h
1138 @comment POSIX.2
1139 @item WRDE_DOOFFS
1140 Leave blank slots at the beginning of the vector of words.
1141 The @code{we_offs} field says how many slots to leave.
1142 The blank slots contain null pointers.
1143
1144 @comment wordexp.h
1145 @comment POSIX.2
1146 @item WRDE_NOCMD
1147 Don't do command substitution; if the input requests command substitution,
1148 report an error.
1149
1150 @comment wordexp.h
1151 @comment POSIX.2
1152 @item WRDE_REUSE
1153 Reuse a word vector made by a previous call to @code{wordexp}.
1154 Instead of allocating a new vector of words, this call to @code{wordexp}
1155 will use the vector that already exists (making it larger if necessary).
1156
1157 Note that the vector may move, so it is not safe to save an old pointer
1158 and use it again after calling @code{wordexp}.  You must fetch
1159 @code{we_pathv} anew after each call.
1160
1161 @comment wordexp.h
1162 @comment POSIX.2
1163 @item WRDE_SHOWERR
1164 Do show any error messages printed by commands run by command substitution.
1165 More precisely, allow these commands to inherit the standard error output
1166 stream of the current process.  By default, @code{wordexp} gives these
1167 commands a standard error stream that discards all output.
1168
1169 @comment wordexp.h
1170 @comment POSIX.2
1171 @item WRDE_UNDEF
1172 If the input refers to a shell variable that is not defined, report an
1173 error.
1174 @end table
1175
1176 @node Wordexp Example
1177 @subsection @code{wordexp} Example
1178
1179 Here is an example of using @code{wordexp} to expand several strings
1180 and use the results to run a shell command.  It also shows the use of
1181 @code{WRDE_APPEND} to concatenate the expansions and of @code{wordfree}
1182 to free the space allocated by @code{wordexp}.
1183
1184 @smallexample
1185 int
1186 expand_and_execute (const char *program, const char *options)
1187 @{
1188   wordexp_t result;
1189   pid_t pid
1190   int status, i;
1191
1192   /* @r{Expand the string for the program to run.}  */
1193   switch (wordexp (program, &result, 0))
1194     @{
1195     case 0:                     /* @r{Successful}.  */
1196       break;
1197     case WRDE_NOSPACE:
1198       /* @r{If the error was @code{WRDE_NOSPACE},}
1199          @r{then perhaps part of the result was allocated.}  */
1200       wordfree (&result);
1201     default:                    /* @r{Some other error.}  */
1202       return -1;
1203     @}
1204
1205   /* @r{Expand the strings specified for the arguments.}  */
1206   for (i = 0; args[i]; i++)
1207     @{
1208       if (wordexp (options, &result, WRDE_APPEND))
1209         @{
1210           wordfree (&result);
1211           return -1;
1212         @}
1213     @}
1214
1215   pid = fork ();
1216   if (pid == 0)
1217     @{
1218       /* @r{This is the child process.  Execute the command.} */
1219       execv (result.we_wordv[0], result.we_wordv);
1220       exit (EXIT_FAILURE);
1221     @}
1222   else if (pid < 0)
1223     /* @r{The fork failed.  Report failure.}  */
1224     status = -1;
1225   else
1226     /* @r{This is the parent process.  Wait for the child to complete.}  */
1227     if (waitpid (pid, &status, 0) != pid)
1228       status = -1;
1229
1230   wordfree (&result);
1231   return status;
1232 @}
1233 @end smallexample
1234
1235
1236 @c No sense finishing this for here.
1237 @ignore
1238 @node Tilde Expansion
1239 @subsection Details of Tilde Expansion
1240
1241 It's a standard part of shell syntax that you can use @samp{~} at the
1242 beginning of a file name to stand for your own home directory.  You
1243 can use @samp{~@var{user}} to stand for @var{user}'s home directory.
1244
1245 @dfn{Tilde expansion} is the process of converting these abbreviations
1246 to the directory names that they stand for.
1247
1248 Tilde expansion applies to the @samp{~} plus all following characters up
1249 to whitespace or a slash.  It takes place only at the beginning of a
1250 word, and only if none of the characters to be transformed is quoted in
1251 any way.
1252
1253 Plain @samp{~} uses the value of the environment variable @code{HOME}
1254 as the proper home directory name.  @samp{~} followed by a user name
1255 uses @code{getpwname} to look up that user in the user database, and
1256 uses whatever directory is recorded there.  Thus, @samp{~} followed
1257 by your own name can give different results from plain @samp{~}, if
1258 the value of @code{HOME} is not really your home directory.
1259
1260 @node Variable Substitution
1261 @subsection Details of Variable Substitution
1262
1263 Part of ordinary shell syntax is the use of @samp{$@var{variable}} to
1264 substitute the value of a shell variable into a command.  This is called
1265 @dfn{variable substitution}, and it is one part of doing word expansion.
1266
1267 There are two basic ways you can write a variable reference for
1268 substitution:
1269
1270 @table @code
1271 @item $@{@var{variable}@}
1272 If you write braces around the variable name, then it is completely
1273 unambiguous where the variable name ends.  You can concatenate
1274 additional letters onto the end of the variable value by writing them
1275 immediately after the close brace.  For example, @samp{$@{foo@}s}
1276 expands into @samp{tractors}.
1277
1278 @item $@var{variable}
1279 If you do not put braces around the variable name, then the variable
1280 name consists of all the alphanumeric characters and underscores that
1281 follow the @samp{$}.  The next punctuation character ends the variable
1282 name.  Thus, @samp{$foo-bar} refers to the variable @code{foo} and expands
1283 into @samp{tractor-bar}.
1284 @end table
1285
1286 When you use braces, you can also use various constructs to modify the
1287 value that is substituted, or test it in various ways.
1288
1289 @table @code
1290 @item $@{@var{variable}:-@var{default}@}
1291 Substitute the value of @var{variable}, but if that is empty or
1292 undefined, use @var{default} instead.
1293
1294 @item $@{@var{variable}:=@var{default}@}
1295 Substitute the value of @var{variable}, but if that is empty or
1296 undefined, use @var{default} instead and set the variable to
1297 @var{default}.
1298
1299 @item $@{@var{variable}:?@var{message}@}
1300 If @var{variable} is defined and not empty, substitute its value.
1301
1302 Otherwise, print @var{message} as an error message on the standard error
1303 stream, and consider word expansion a failure.
1304
1305 @c ??? How does wordexp report such an error?
1306
1307 @item $@{@var{variable}:+@var{replacement}@}
1308 Substitute @var{replacement}, but only if @var{variable} is defined and
1309 nonempty.  Otherwise, substitute nothing for this construct.
1310 @end table
1311
1312 @table @code
1313 @item $@{#@var{variable}@}
1314 Substitute a numeral which expresses in base ten the number of
1315 characters in the value of @var{variable}.  @samp{$@{#foo@}} stands for
1316 @samp{7}, because @samp{tractor} is seven characters.
1317 @end table
1318
1319 These variants of variable substitution let you remove part of the
1320 variable's value before substituting it.  The @var{prefix} and
1321 @var{suffix} are not mere strings; they are wildcard patterns, just
1322 like the patterns that you use to match multiple file names.  But
1323 in this context, they match against parts of the variable value
1324 rather than against file names.
1325
1326 @table @code
1327 @item $@{@var{variable}%%@var{suffix}@}
1328 Substitute the value of @var{variable}, but first discard from that
1329 variable any portion at the end that matches the pattern @var{suffix}.
1330
1331 If there is more than one alternative for how to match against
1332 @var{suffix}, this construct uses the longest possible match.
1333
1334 Thus, @samp{$@{foo%%r*@}} substitutes @samp{t}, because the largest
1335 match for @samp{r*} at the end of @samp{tractor} is @samp{ractor}.
1336
1337 @item $@{@var{variable}%@var{suffix}@}
1338 Substitute the value of @var{variable}, but first discard from that
1339 variable any portion at the end that matches the pattern @var{suffix}.
1340
1341 If there is more than one alternative for how to match against
1342 @var{suffix}, this construct uses the shortest possible alternative.
1343
1344 Thus, @samp{$@{foo%%r*@}} substitutes @samp{tracto}, because the shortest
1345 match for @samp{r*} at the end of @samp{tractor} is just @samp{r}.
1346
1347 @item $@{@var{variable}##@var{prefix}@}
1348 Substitute the value of @var{variable}, but first discard from that
1349 variable any portion at the beginning that matches the pattern @var{prefix}.
1350
1351 If there is more than one alternative for how to match against
1352 @var{prefix}, this construct uses the longest possible match.
1353
1354 Thus, @samp{$@{foo%%r*@}} substitutes @samp{t}, because the largest
1355 match for @samp{r*} at the end of @samp{tractor} is @samp{ractor}.
1356
1357 @item $@{@var{variable}#@var{prefix}@}
1358 Substitute the value of @var{variable}, but first discard from that
1359 variable any portion at the beginning that matches the pattern @var{prefix}.
1360
1361 If there is more than one alternative for how to match against
1362 @var{prefix}, this construct uses the shortest possible alternative.
1363
1364 Thus, @samp{$@{foo%%r*@}} substitutes @samp{tracto}, because the shortest
1365 match for @samp{r*} at the end of @samp{tractor} is just @samp{r}.
1366
1367 @end ignore