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