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