596b72d4fa6e53e904af38100b6d8a5dbcaed8fb
[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 @end table
470
471 Calling @code{glob} will in most cases allocate resources which are used
472 to represent the result of the function call.  If the same object of
473 type @code{glob_t} is used in multiple call to @code{glob} the resources
474 are freed or reused so that no leaks appear.  But this does not include
475 the time when all @code{glob} calls are done.
476
477 @comment glob.h
478 @comment POSIX.2
479 @deftypefun void globfree (glob_t *@var{pglob})
480 The @code{globfree} function frees all resources allocated by previous
481 calls to @code{glob} associated with the object pointed to by
482 @var{pglob}.  This function should be called whenever the currently used
483 @code{glob_t} typed object isn't used anymore.
484 @end deftypefun
485
486
487 @node Regular Expressions
488 @section Regular Expression Matching
489
490 The GNU C library supports two interfaces for matching regular
491 expressions.  One is the standard POSIX.2 interface, and the other is
492 what the GNU system has had for many years.
493
494 Both interfaces are declared in the header file @file{regex.h}.
495 If you define @w{@code{_POSIX_C_SOURCE}}, then only the POSIX.2
496 functions, structures, and constants are declared.
497 @c !!! we only document the POSIX.2 interface here!!
498
499 @menu
500 * POSIX Regexp Compilation::    Using @code{regcomp} to prepare to match.
501 * Flags for POSIX Regexps::     Syntax variations for @code{regcomp}.
502 * Matching POSIX Regexps::      Using @code{regexec} to match the compiled
503                                    pattern that you get from @code{regcomp}.
504 * Regexp Subexpressions::       Finding which parts of the string were matched.
505 * Subexpression Complications:: Find points of which parts were matched.
506 * Regexp Cleanup::              Freeing storage; reporting errors.
507 @end menu
508
509 @node POSIX Regexp Compilation
510 @subsection POSIX Regular Expression Compilation
511
512 Before you can actually match a regular expression, you must
513 @dfn{compile} it.  This is not true compilation---it produces a special
514 data structure, not machine instructions.  But it is like ordinary
515 compilation in that its purpose is to enable you to ``execute'' the
516 pattern fast.  (@xref{Matching POSIX Regexps}, for how to use the
517 compiled regular expression for matching.)
518
519 There is a special data type for compiled regular expressions:
520
521 @comment regex.h
522 @comment POSIX.2
523 @deftp {Data Type} regex_t
524 This type of object holds a compiled regular expression.
525 It is actually a structure.  It has just one field that your programs
526 should look at:
527
528 @table @code
529 @item re_nsub
530 This field holds the number of parenthetical subexpressions in the
531 regular expression that was compiled.
532 @end table
533
534 There are several other fields, but we don't describe them here, because
535 only the functions in the library should use them.
536 @end deftp
537
538 After you create a @code{regex_t} object, you can compile a regular
539 expression into it by calling @code{regcomp}.
540
541 @comment regex.h
542 @comment POSIX.2
543 @deftypefun int regcomp (regex_t *@var{compiled}, const char *@var{pattern}, int @var{cflags})
544 The function @code{regcomp} ``compiles'' a regular expression into a
545 data structure that you can use with @code{regexec} to match against a
546 string.  The compiled regular expression format is designed for
547 efficient matching.  @code{regcomp} stores it into @code{*@var{compiled}}.
548
549 It's up to you to allocate an object of type @code{regex_t} and pass its
550 address to @code{regcomp}.
551
552 The argument @var{cflags} lets you specify various options that control
553 the syntax and semantics of regular expressions.  @xref{Flags for POSIX
554 Regexps}.
555
556 If you use the flag @code{REG_NOSUB}, then @code{regcomp} omits from
557 the compiled regular expression the information necessary to record
558 how subexpressions actually match.  In this case, you might as well
559 pass @code{0} for the @var{matchptr} and @var{nmatch} arguments when
560 you call @code{regexec}.
561
562 If you don't use @code{REG_NOSUB}, then the compiled regular expression
563 does have the capacity to record how subexpressions match.  Also,
564 @code{regcomp} tells you how many subexpressions @var{pattern} has, by
565 storing the number in @code{@var{compiled}->re_nsub}.  You can use that
566 value to decide how long an array to allocate to hold information about
567 subexpression matches.
568
569 @code{regcomp} returns @code{0} if it succeeds in compiling the regular
570 expression; otherwise, it returns a nonzero error code (see the table
571 below).  You can use @code{regerror} to produce an error message string
572 describing the reason for a nonzero value; see @ref{Regexp Cleanup}.
573
574 @end deftypefun
575
576 Here are the possible nonzero values that @code{regcomp} can return:
577
578 @table @code
579 @comment regex.h
580 @comment POSIX.2
581 @item REG_BADBR
582 There was an invalid @samp{\@{@dots{}\@}} construct in the regular
583 expression.  A valid @samp{\@{@dots{}\@}} construct must contain either
584 a single number, or two numbers in increasing order separated by a
585 comma.
586
587 @comment regex.h
588 @comment POSIX.2
589 @item REG_BADPAT
590 There was a syntax error in the regular expression.
591
592 @comment regex.h
593 @comment POSIX.2
594 @item REG_BADRPT
595 A repetition operator such as @samp{?} or @samp{*} appeared in a bad
596 position (with no preceding subexpression to act on).
597
598 @comment regex.h
599 @comment POSIX.2
600 @item REG_ECOLLATE
601 The regular expression referred to an invalid collating element (one not
602 defined in the current locale for string collation).  @xref{Locale
603 Categories}.
604
605 @comment regex.h
606 @comment POSIX.2
607 @item REG_ECTYPE
608 The regular expression referred to an invalid character class name.
609
610 @comment regex.h
611 @comment POSIX.2
612 @item REG_EESCAPE
613 The regular expression ended with @samp{\}.
614
615 @comment regex.h
616 @comment POSIX.2
617 @item REG_ESUBREG
618 There was an invalid number in the @samp{\@var{digit}} construct.
619
620 @comment regex.h
621 @comment POSIX.2
622 @item REG_EBRACK
623 There were unbalanced square brackets in the regular expression.
624
625 @comment regex.h
626 @comment POSIX.2
627 @item REG_EPAREN
628 An extended regular expression had unbalanced parentheses,
629 or a basic regular expression had unbalanced @samp{\(} and @samp{\)}.
630
631 @comment regex.h
632 @comment POSIX.2
633 @item REG_EBRACE
634 The regular expression had unbalanced @samp{\@{} and @samp{\@}}.
635
636 @comment regex.h
637 @comment POSIX.2
638 @item REG_ERANGE
639 One of the endpoints in a range expression was invalid.
640
641 @comment regex.h
642 @comment POSIX.2
643 @item REG_ESPACE
644 @code{regcomp} ran out of memory.
645 @end table
646
647 @node Flags for POSIX Regexps
648 @subsection Flags for POSIX Regular Expressions
649
650 These are the bit flags that you can use in the @var{cflags} operand when
651 compiling a regular expression with @code{regcomp}.
652
653 @table @code
654 @comment regex.h
655 @comment POSIX.2
656 @item REG_EXTENDED
657 Treat the pattern as an extended regular expression, rather than as a
658 basic regular expression.
659
660 @comment regex.h
661 @comment POSIX.2
662 @item REG_ICASE
663 Ignore case when matching letters.
664
665 @comment regex.h
666 @comment POSIX.2
667 @item REG_NOSUB
668 Don't bother storing the contents of the @var{matches-ptr} array.
669
670 @comment regex.h
671 @comment POSIX.2
672 @item REG_NEWLINE
673 Treat a newline in @var{string} as dividing @var{string} into multiple
674 lines, so that @samp{$} can match before the newline and @samp{^} can
675 match after.  Also, don't permit @samp{.} to match a newline, and don't
676 permit @samp{[^@dots{}]} to match a newline.
677
678 Otherwise, newline acts like any other ordinary character.
679 @end table
680
681 @node Matching POSIX Regexps
682 @subsection Matching a Compiled POSIX Regular Expression
683
684 Once you have compiled a regular expression, as described in @ref{POSIX
685 Regexp Compilation}, you can match it against strings using
686 @code{regexec}.  A match anywhere inside the string counts as success,
687 unless the regular expression contains anchor characters (@samp{^} or
688 @samp{$}).
689
690 @comment regex.h
691 @comment POSIX.2
692 @deftypefun int regexec (regex_t *@var{compiled}, char *@var{string}, size_t @var{nmatch}, regmatch_t @var{matchptr} @t{[]}, int @var{eflags})
693 This function tries to match the compiled regular expression
694 @code{*@var{compiled}} against @var{string}.
695
696 @code{regexec} returns @code{0} if the regular expression matches;
697 otherwise, it returns a nonzero value.  See the table below for
698 what nonzero values mean.  You can use @code{regerror} to produce an
699 error message string describing the reason for a nonzero value;
700 see @ref{Regexp Cleanup}.
701
702 The argument @var{eflags} is a word of bit flags that enable various
703 options.
704
705 If you want to get information about what part of @var{string} actually
706 matched the regular expression or its subexpressions, use the arguments
707 @var{matchptr} and @var{nmatch}.  Otherwise, pass @code{0} for
708 @var{nmatch}, and @code{NULL} for @var{matchptr}.  @xref{Regexp
709 Subexpressions}.
710 @end deftypefun
711
712 You must match the regular expression with the same set of current
713 locales that were in effect when you compiled the regular expression.
714
715 The function @code{regexec} accepts the following flags in the
716 @var{eflags} argument:
717
718 @table @code
719 @comment regex.h
720 @comment POSIX.2
721 @item REG_NOTBOL
722 Do not regard the beginning of the specified string as the beginning of
723 a line; more generally, don't make any assumptions about what text might
724 precede it.
725
726 @comment regex.h
727 @comment POSIX.2
728 @item REG_NOTEOL
729 Do not regard the end of the specified string as the end of a line; more
730 generally, don't make any assumptions about what text might follow it.
731 @end table
732
733 Here are the possible nonzero values that @code{regexec} can return:
734
735 @table @code
736 @comment regex.h
737 @comment POSIX.2
738 @item REG_NOMATCH
739 The pattern didn't match the string.  This isn't really an error.
740
741 @comment regex.h
742 @comment POSIX.2
743 @item REG_ESPACE
744 @code{regexec} ran out of memory.
745 @end table
746
747 @node Regexp Subexpressions
748 @subsection Match Results with Subexpressions
749
750 When @code{regexec} matches parenthetical subexpressions of
751 @var{pattern}, it records which parts of @var{string} they match.  It
752 returns that information by storing the offsets into an array whose
753 elements are structures of type @code{regmatch_t}.  The first element of
754 the array (index @code{0}) records the part of the string that matched
755 the entire regular expression.  Each other element of the array records
756 the beginning and end of the part that matched a single parenthetical
757 subexpression.
758
759 @comment regex.h
760 @comment POSIX.2
761 @deftp {Data Type} regmatch_t
762 This is the data type of the @var{matcharray} array that you pass to
763 @code{regexec}.  It contains two structure fields, as follows:
764
765 @table @code
766 @item rm_so
767 The offset in @var{string} of the beginning of a substring.  Add this
768 value to @var{string} to get the address of that part.
769
770 @item rm_eo
771 The offset in @var{string} of the end of the substring.
772 @end table
773 @end deftp
774
775 @comment regex.h
776 @comment POSIX.2
777 @deftp {Data Type} regoff_t
778 @code{regoff_t} is an alias for another signed integer type.
779 The fields of @code{regmatch_t} have type @code{regoff_t}.
780 @end deftp
781
782 The @code{regmatch_t} elements correspond to subexpressions
783 positionally; the first element (index @code{1}) records where the first
784 subexpression matched, the second element records the second
785 subexpression, and so on.  The order of the subexpressions is the order
786 in which they begin.
787
788 When you call @code{regexec}, you specify how long the @var{matchptr}
789 array is, with the @var{nmatch} argument.  This tells @code{regexec} how
790 many elements to store.  If the actual regular expression has more than
791 @var{nmatch} subexpressions, then you won't get offset information about
792 the rest of them.  But this doesn't alter whether the pattern matches a
793 particular string or not.
794
795 If you don't want @code{regexec} to return any information about where
796 the subexpressions matched, you can either supply @code{0} for
797 @var{nmatch}, or use the flag @code{REG_NOSUB} when you compile the
798 pattern with @code{regcomp}.
799
800 @node Subexpression Complications
801 @subsection Complications in Subexpression Matching
802
803 Sometimes a subexpression matches a substring of no characters.  This
804 happens when @samp{f\(o*\)} matches the string @samp{fum}.  (It really
805 matches just the @samp{f}.)  In this case, both of the offsets identify
806 the point in the string where the null substring was found.  In this
807 example, the offsets are both @code{1}.
808
809 Sometimes the entire regular expression can match without using some of
810 its subexpressions at all---for example, when @samp{ba\(na\)*} matches the
811 string @samp{ba}, the parenthetical subexpression is not used.  When
812 this happens, @code{regexec} stores @code{-1} in both fields of the
813 element for that subexpression.
814
815 Sometimes matching the entire regular expression can match a particular
816 subexpression more than once---for example, when @samp{ba\(na\)*}
817 matches the string @samp{bananana}, the parenthetical subexpression
818 matches three times.  When this happens, @code{regexec} usually stores
819 the offsets of the last part of the string that matched the
820 subexpression.  In the case of @samp{bananana}, these offsets are
821 @code{6} and @code{8}.
822
823 But the last match is not always the one that is chosen.  It's more
824 accurate to say that the last @emph{opportunity} to match is the one
825 that takes precedence.  What this means is that when one subexpression
826 appears within another, then the results reported for the inner
827 subexpression reflect whatever happened on the last match of the outer
828 subexpression.  For an example, consider @samp{\(ba\(na\)*s \)*} matching
829 the string @samp{bananas bas }.  The last time the inner expression
830 actually matches is near the end of the first word.  But it is
831 @emph{considered} again in the second word, and fails to match there.
832 @code{regexec} reports nonuse of the ``na'' subexpression.
833
834 Another place where this rule applies is when the regular expression
835 @w{@samp{\(ba\(na\)*s \|nefer\(ti\)* \)*}} matches @samp{bananas nefertiti}.
836 The ``na'' subexpression does match in the first word, but it doesn't
837 match in the second word because the other alternative is used there.
838 Once again, the second repetition of the outer subexpression overrides
839 the first, and within that second repetition, the ``na'' subexpression
840 is not used.  So @code{regexec} reports nonuse of the ``na''
841 subexpression.
842
843 @node Regexp Cleanup
844 @subsection POSIX Regexp Matching Cleanup
845
846 When you are finished using a compiled regular expression, you can
847 free the storage it uses by calling @code{regfree}.
848
849 @comment regex.h
850 @comment POSIX.2
851 @deftypefun void regfree (regex_t *@var{compiled})
852 Calling @code{regfree} frees all the storage that @code{*@var{compiled}}
853 points to.  This includes various internal fields of the @code{regex_t}
854 structure that aren't documented in this manual.
855
856 @code{regfree} does not free the object @code{*@var{compiled}} itself.
857 @end deftypefun
858
859 You should always free the space in a @code{regex_t} structure with
860 @code{regfree} before using the structure to compile another regular
861 expression.
862
863 When @code{regcomp} or @code{regexec} reports an error, you can use
864 the function @code{regerror} to turn it into an error message string.
865
866 @comment regex.h
867 @comment POSIX.2
868 @deftypefun size_t regerror (int @var{errcode}, regex_t *@var{compiled}, char *@var{buffer}, size_t @var{length})
869 This function produces an error message string for the error code
870 @var{errcode}, and stores the string in @var{length} bytes of memory
871 starting at @var{buffer}.  For the @var{compiled} argument, supply the
872 same compiled regular expression structure that @code{regcomp} or
873 @code{regexec} was working with when it got the error.  Alternatively,
874 you can supply @code{NULL} for @var{compiled}; you will still get a
875 meaningful error message, but it might not be as detailed.
876
877 If the error message can't fit in @var{length} bytes (including a
878 terminating null character), then @code{regerror} truncates it.
879 The string that @code{regerror} stores is always null-terminated
880 even if it has been truncated.
881
882 The return value of @code{regerror} is the minimum length needed to
883 store the entire error message.  If this is less than @var{length}, then
884 the error message was not truncated, and you can use it.  Otherwise, you
885 should call @code{regerror} again with a larger buffer.
886
887 Here is a function which uses @code{regerror}, but always dynamically
888 allocates a buffer for the error message:
889
890 @smallexample
891 char *get_regerror (int errcode, regex_t *compiled)
892 @{
893   size_t length = regerror (errcode, compiled, NULL, 0);
894   char *buffer = xmalloc (length);
895   (void) regerror (errcode, compiled, buffer, length);
896   return buffer;
897 @}
898 @end smallexample
899 @end deftypefun
900
901 @c !!!! this is not actually in the library....
902 @node Word Expansion
903 @section Shell-Style Word Expansion
904 @cindex word expansion
905 @cindex expansion of shell words
906
907 @dfn{Word expansion} means the process of splitting a string into
908 @dfn{words} and substituting for variables, commands, and wildcards
909 just as the shell does.
910
911 For example, when you write @samp{ls -l foo.c}, this string is split
912 into three separate words---@samp{ls}, @samp{-l} and @samp{foo.c}.
913 This is the most basic function of word expansion.
914
915 When you write @samp{ls *.c}, this can become many words, because
916 the word @samp{*.c} can be replaced with any number of file names.
917 This is called @dfn{wildcard expansion}, and it is also a part of
918 word expansion.
919
920 When you use @samp{echo $PATH} to print your path, you are taking
921 advantage of @dfn{variable substitution}, which is also part of word
922 expansion.
923
924 Ordinary programs can perform word expansion just like the shell by
925 calling the library function @code{wordexp}.
926
927 @menu
928 * Expansion Stages::    What word expansion does to a string.
929 * Calling Wordexp::     How to call @code{wordexp}.
930 * Flags for Wordexp::   Options you can enable in @code{wordexp}.
931 * Wordexp Example::     A sample program that does word expansion.
932 @end menu
933
934 @node Expansion Stages
935 @subsection The Stages of Word Expansion
936
937 When word expansion is applied to a sequence of words, it performs the
938 following transformations in the order shown here:
939
940 @enumerate
941 @item
942 @cindex tilde expansion
943 @dfn{Tilde expansion}: Replacement of @samp{~foo} with the name of
944 the home directory of @samp{foo}.
945
946 @item
947 Next, three different transformations are applied in the same step,
948 from left to right:
949
950 @itemize @bullet
951 @item
952 @cindex variable substitution
953 @cindex substitution of variables and commands
954 @dfn{Variable substitution}: Environment variables are substituted for
955 references such as @samp{$foo}.
956
957 @item
958 @cindex command substitution
959 @dfn{Command substitution}: Constructs such as @w{@samp{`cat foo`}} and
960 the equivalent @w{@samp{$(cat foo)}} are replaced with the output from
961 the inner command.
962
963 @item
964 @cindex arithmetic expansion
965 @dfn{Arithmetic expansion}: Constructs such as @samp{$(($x-1))} are
966 replaced with the result of the arithmetic computation.
967 @end itemize
968
969 @item
970 @cindex field splitting
971 @dfn{Field splitting}: subdivision of the text into @dfn{words}.
972
973 @item
974 @cindex wildcard expansion
975 @dfn{Wildcard expansion}: The replacement of a construct such as @samp{*.c}
976 with a list of @samp{.c} file names.  Wildcard expansion applies to an
977 entire word at a time, and replaces that word with 0 or more file names
978 that are themselves words.
979
980 @item
981 @cindex quote removal
982 @cindex removal of quotes
983 @dfn{Quote removal}: The deletion of string-quotes, now that they have
984 done their job by inhibiting the above transformations when appropriate.
985 @end enumerate
986
987 For the details of these transformations, and how to write the constructs
988 that use them, see @w{@cite{The BASH Manual}} (to appear).
989
990 @node Calling Wordexp
991 @subsection Calling @code{wordexp}
992
993 All the functions, constants and data types for word expansion are
994 declared in the header file @file{wordexp.h}.
995
996 Word expansion produces a vector of words (strings).  To return this
997 vector, @code{wordexp} uses a special data type, @code{wordexp_t}, which
998 is a structure.  You pass @code{wordexp} the address of the structure,
999 and it fills in the structure's fields to tell you about the results.
1000
1001 @comment wordexp.h
1002 @comment POSIX.2
1003 @deftp {Data Type} {wordexp_t}
1004 This data type holds a pointer to a word vector.  More precisely, it
1005 records both the address of the word vector and its size.
1006
1007 @table @code
1008 @item we_wordc
1009 The number of elements in the vector.
1010
1011 @item we_wordv
1012 The address of the vector.  This field has type @w{@code{char **}}.
1013
1014 @item we_offs
1015 The offset of the first real element of the vector, from its nominal
1016 address in the @code{we_wordv} field.  Unlike the other fields, this
1017 is always an input to @code{wordexp}, rather than an output from it.
1018
1019 If you use a nonzero offset, then that many elements at the beginning of
1020 the vector are left empty.  (The @code{wordexp} function fills them with
1021 null pointers.)
1022
1023 The @code{we_offs} field is meaningful only if you use the
1024 @code{WRDE_DOOFFS} flag.  Otherwise, the offset is always zero
1025 regardless of what is in this field, and the first real element comes at
1026 the beginning of the vector.
1027 @end table
1028 @end deftp
1029
1030 @comment wordexp.h
1031 @comment POSIX.2
1032 @deftypefun int wordexp (const char *@var{words}, wordexp_t *@var{word-vector-ptr}, int @var{flags})
1033 Perform word expansion on the string @var{words}, putting the result in
1034 a newly allocated vector, and store the size and address of this vector
1035 into @code{*@var{word-vector-ptr}}.  The argument @var{flags} is a
1036 combination of bit flags; see @ref{Flags for Wordexp}, for details of
1037 the flags.
1038
1039 You shouldn't use any of the characters @samp{|&;<>} in the string
1040 @var{words} unless they are quoted; likewise for newline.  If you use
1041 these characters unquoted, you will get the @code{WRDE_BADCHAR} error
1042 code.  Don't use parentheses or braces unless they are quoted or part of
1043 a word expansion construct.  If you use quotation characters @samp{'"`},
1044 they should come in pairs that balance.
1045
1046 The results of word expansion are a sequence of words.  The function
1047 @code{wordexp} allocates a string for each resulting word, then
1048 allocates a vector of type @code{char **} to store the addresses of
1049 these strings.  The last element of the vector is a null pointer.
1050 This vector is called the @dfn{word vector}.
1051
1052 To return this vector, @code{wordexp} stores both its address and its
1053 length (number of elements, not counting the terminating null pointer)
1054 into @code{*@var{word-vector-ptr}}.
1055
1056 If @code{wordexp} succeeds, it returns 0.  Otherwise, it returns one
1057 of these error codes:
1058
1059 @table @code
1060 @comment wordexp.h
1061 @comment POSIX.2
1062 @item WRDE_BADCHAR
1063 The input string @var{words} contains an unquoted invalid character such
1064 as @samp{|}.
1065
1066 @comment wordexp.h
1067 @comment POSIX.2
1068 @item WRDE_BADVAL
1069 The input string refers to an undefined shell variable, and you used the flag
1070 @code{WRDE_UNDEF} to forbid such references.
1071
1072 @comment wordexp.h
1073 @comment POSIX.2
1074 @item WRDE_CMDSUB
1075 The input string uses command substitution, and you used the flag
1076 @code{WRDE_NOCMD} to forbid command substitution.
1077
1078 @comment wordexp.h
1079 @comment POSIX.2
1080 @item WRDE_NOSPACE
1081 It was impossible to allocate memory to hold the result.  In this case,
1082 @code{wordexp} can store part of the results---as much as it could
1083 allocate room for.
1084
1085 @comment wordexp.h
1086 @comment POSIX.2
1087 @item WRDE_SYNTAX
1088 There was a syntax error in the input string.  For example, an unmatched
1089 quoting character is a syntax error.
1090 @end table
1091 @end deftypefun
1092
1093 @comment wordexp.h
1094 @comment POSIX.2
1095 @deftypefun void wordfree (wordexp_t *@var{word-vector-ptr})
1096 Free the storage used for the word-strings and vector that
1097 @code{*@var{word-vector-ptr}} points to.  This does not free the
1098 structure @code{*@var{word-vector-ptr}} itself---only the other
1099 data it points to.
1100 @end deftypefun
1101
1102 @node Flags for Wordexp
1103 @subsection Flags for Word Expansion
1104
1105 This section describes the flags that you can specify in the
1106 @var{flags} argument to @code{wordexp}.  Choose the flags you want,
1107 and combine them with the C operator @code{|}.
1108
1109 @table @code
1110 @comment wordexp.h
1111 @comment POSIX.2
1112 @item WRDE_APPEND
1113 Append the words from this expansion to the vector of words produced by
1114 previous calls to @code{wordexp}.  This way you can effectively expand
1115 several words as if they were concatenated with spaces between them.
1116
1117 In order for appending to work, you must not modify the contents of the
1118 word vector structure between calls to @code{wordexp}.  And, if you set
1119 @code{WRDE_DOOFFS} in the first call to @code{wordexp}, you must also
1120 set it when you append to the results.
1121
1122 @comment wordexp.h
1123 @comment POSIX.2
1124 @item WRDE_DOOFFS
1125 Leave blank slots at the beginning of the vector of words.
1126 The @code{we_offs} field says how many slots to leave.
1127 The blank slots contain null pointers.
1128
1129 @comment wordexp.h
1130 @comment POSIX.2
1131 @item WRDE_NOCMD
1132 Don't do command substitution; if the input requests command substitution,
1133 report an error.
1134
1135 @comment wordexp.h
1136 @comment POSIX.2
1137 @item WRDE_REUSE
1138 Reuse a word vector made by a previous call to @code{wordexp}.
1139 Instead of allocating a new vector of words, this call to @code{wordexp}
1140 will use the vector that already exists (making it larger if necessary).
1141
1142 Note that the vector may move, so it is not safe to save an old pointer
1143 and use it again after calling @code{wordexp}.  You must fetch
1144 @code{we_pathv} anew after each call.
1145
1146 @comment wordexp.h
1147 @comment POSIX.2
1148 @item WRDE_SHOWERR
1149 Do show any error messages printed by commands run by command substitution.
1150 More precisely, allow these commands to inherit the standard error output
1151 stream of the current process.  By default, @code{wordexp} gives these
1152 commands a standard error stream that discards all output.
1153
1154 @comment wordexp.h
1155 @comment POSIX.2
1156 @item WRDE_UNDEF
1157 If the input refers to a shell variable that is not defined, report an
1158 error.
1159 @end table
1160
1161 @node Wordexp Example
1162 @subsection @code{wordexp} Example
1163
1164 Here is an example of using @code{wordexp} to expand several strings
1165 and use the results to run a shell command.  It also shows the use of
1166 @code{WRDE_APPEND} to concatenate the expansions and of @code{wordfree}
1167 to free the space allocated by @code{wordexp}.
1168
1169 @smallexample
1170 int
1171 expand_and_execute (const char *program, const char *options)
1172 @{
1173   wordexp_t result;
1174   pid_t pid
1175   int status, i;
1176
1177   /* @r{Expand the string for the program to run.}  */
1178   switch (wordexp (program, &result, 0))
1179     @{
1180     case 0:                     /* @r{Successful}.  */
1181       break;
1182     case WRDE_NOSPACE:
1183       /* @r{If the error was @code{WRDE_NOSPACE},}
1184          @r{then perhaps part of the result was allocated.}  */
1185       wordfree (&result);
1186     default:                    /* @r{Some other error.}  */
1187       return -1;
1188     @}
1189
1190   /* @r{Expand the strings specified for the arguments.}  */
1191   for (i = 0; args[i]; i++)
1192     @{
1193       if (wordexp (options, &result, WRDE_APPEND))
1194         @{
1195           wordfree (&result);
1196           return -1;
1197         @}
1198     @}
1199
1200   pid = fork ();
1201   if (pid == 0)
1202     @{
1203       /* @r{This is the child process.  Execute the command.} */
1204       execv (result.we_wordv[0], result.we_wordv);
1205       exit (EXIT_FAILURE);
1206     @}
1207   else if (pid < 0)
1208     /* @r{The fork failed.  Report failure.}  */
1209     status = -1;
1210   else
1211     /* @r{This is the parent process.  Wait for the child to complete.}  */
1212     if (waitpid (pid, &status, 0) != pid)
1213       status = -1;
1214
1215   wordfree (&result);
1216   return status;
1217 @}
1218 @end smallexample
1219
1220
1221 @c No sense finishing this for here.
1222 @ignore
1223 @node Tilde Expansion
1224 @subsection Details of Tilde Expansion
1225
1226 It's a standard part of shell syntax that you can use @samp{~} at the
1227 beginning of a file name to stand for your own home directory.  You
1228 can use @samp{~@var{user}} to stand for @var{user}'s home directory.
1229
1230 @dfn{Tilde expansion} is the process of converting these abbreviations
1231 to the directory names that they stand for.
1232
1233 Tilde expansion applies to the @samp{~} plus all following characters up
1234 to whitespace or a slash.  It takes place only at the beginning of a
1235 word, and only if none of the characters to be transformed is quoted in
1236 any way.
1237
1238 Plain @samp{~} uses the value of the environment variable @code{HOME}
1239 as the proper home directory name.  @samp{~} followed by a user name
1240 uses @code{getpwname} to look up that user in the user database, and
1241 uses whatever directory is recorded there.  Thus, @samp{~} followed
1242 by your own name can give different results from plain @samp{~}, if
1243 the value of @code{HOME} is not really your home directory.
1244
1245 @node Variable Substitution
1246 @subsection Details of Variable Substitution
1247
1248 Part of ordinary shell syntax is the use of @samp{$@var{variable}} to
1249 substitute the value of a shell variable into a command.  This is called
1250 @dfn{variable substitution}, and it is one part of doing word expansion.
1251
1252 There are two basic ways you can write a variable reference for
1253 substitution:
1254
1255 @table @code
1256 @item $@{@var{variable}@}
1257 If you write braces around the variable name, then it is completely
1258 unambiguous where the variable name ends.  You can concatenate
1259 additional letters onto the end of the variable value by writing them
1260 immediately after the close brace.  For example, @samp{$@{foo@}s}
1261 expands into @samp{tractors}.
1262
1263 @item $@var{variable}
1264 If you do not put braces around the variable name, then the variable
1265 name consists of all the alphanumeric characters and underscores that
1266 follow the @samp{$}.  The next punctuation character ends the variable
1267 name.  Thus, @samp{$foo-bar} refers to the variable @code{foo} and expands
1268 into @samp{tractor-bar}.
1269 @end table
1270
1271 When you use braces, you can also use various constructs to modify the
1272 value that is substituted, or test it in various ways.
1273
1274 @table @code
1275 @item $@{@var{variable}:-@var{default}@}
1276 Substitute the value of @var{variable}, but if that is empty or
1277 undefined, use @var{default} instead.
1278
1279 @item $@{@var{variable}:=@var{default}@}
1280 Substitute the value of @var{variable}, but if that is empty or
1281 undefined, use @var{default} instead and set the variable to
1282 @var{default}.
1283
1284 @item $@{@var{variable}:?@var{message}@}
1285 If @var{variable} is defined and not empty, substitute its value.
1286
1287 Otherwise, print @var{message} as an error message on the standard error
1288 stream, and consider word expansion a failure.
1289
1290 @c ??? How does wordexp report such an error?
1291
1292 @item $@{@var{variable}:+@var{replacement}@}
1293 Substitute @var{replacement}, but only if @var{variable} is defined and
1294 nonempty.  Otherwise, substitute nothing for this construct.
1295 @end table
1296
1297 @table @code
1298 @item $@{#@var{variable}@}
1299 Substitute a numeral which expresses in base ten the number of
1300 characters in the value of @var{variable}.  @samp{$@{#foo@}} stands for
1301 @samp{7}, because @samp{tractor} is seven characters.
1302 @end table
1303
1304 These variants of variable substitution let you remove part of the
1305 variable's value before substituting it.  The @var{prefix} and
1306 @var{suffix} are not mere strings; they are wildcard patterns, just
1307 like the patterns that you use to match multiple file names.  But
1308 in this context, they match against parts of the variable value
1309 rather than against file names.
1310
1311 @table @code
1312 @item $@{@var{variable}%%@var{suffix}@}
1313 Substitute the value of @var{variable}, but first discard from that
1314 variable any portion at the end that matches the pattern @var{suffix}.
1315
1316 If there is more than one alternative for how to match against
1317 @var{suffix}, this construct uses the longest possible match.
1318
1319 Thus, @samp{$@{foo%%r*@}} substitutes @samp{t}, because the largest
1320 match for @samp{r*} at the end of @samp{tractor} is @samp{ractor}.
1321
1322 @item $@{@var{variable}%@var{suffix}@}
1323 Substitute the value of @var{variable}, but first discard from that
1324 variable any portion at the end that matches the pattern @var{suffix}.
1325
1326 If there is more than one alternative for how to match against
1327 @var{suffix}, this construct uses the shortest possible alternative.
1328
1329 Thus, @samp{$@{foo%%r*@}} substitutes @samp{tracto}, because the shortest
1330 match for @samp{r*} at the end of @samp{tractor} is just @samp{r}.
1331
1332 @item $@{@var{variable}##@var{prefix}@}
1333 Substitute the value of @var{variable}, but first discard from that
1334 variable any portion at the beginning that matches the pattern @var{prefix}.
1335
1336 If there is more than one alternative for how to match against
1337 @var{prefix}, this construct uses the longest possible match.
1338
1339 Thus, @samp{$@{foo%%r*@}} substitutes @samp{t}, because the largest
1340 match for @samp{r*} at the end of @samp{tractor} is @samp{ractor}.
1341
1342 @item $@{@var{variable}#@var{prefix}@}
1343 Substitute the value of @var{variable}, but first discard from that
1344 variable any portion at the beginning that matches the pattern @var{prefix}.
1345
1346 If there is more than one alternative for how to match against
1347 @var{prefix}, this construct uses the shortest possible alternative.
1348
1349 Thus, @samp{$@{foo%%r*@}} substitutes @samp{tracto}, because the shortest
1350 match for @samp{r*} at the end of @samp{tractor} is just @samp{r}.
1351
1352 @end ignore