Add missing @end table commands.
[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 Glob}, 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 @deftp {Data Type} {wordexp_t}
787 This data type holds a pointer to a word vector.  More precisely, it
788 records both the address of the word vector and its size.
789
790 @table @code
791 @item we_wordc
792 The number of elements in the vector.
793
794 @item we_wordv
795 The address of the vector.  This field has type @code{char **}.
796
797 @item we_offs
798 The offset of the first real element of the vector, from its nominal
799 address in the @code{we_wordv} field.  Unlike the other fields, this
800 is always an input to @code{wordexp}, rather than an output from it.
801
802 If you use a nonzero offset, then that many elements at the beginning of
803 the vector are left empty.  (The @code{wordexp} function fills them with
804 null pointers.)
805
806 The @code{we_offs} field is meaningful only if you use the
807 @code{WRDE_DOOFFS} flag.  Otherwise, the offset is always zero
808 regardless of what is in this field, and the first real element comes at
809 the beginning of the vector.
810 @end table
811 @end deftp
812
813 @deftypefun int wordexp (const char *@var{words}, wordexp_t *@var{word-vector-ptr}, int @var{flags})
814 Perform word expansion on the string @var{words}, putting the result in
815 a newly allocated vector, and store the size and address of this vector
816 into @code{*@var{word-vector-ptr}}.  The argument @var{flags} is a
817 combination of bit flags; see @ref{Flags for Wordexp}, for details of
818 the flags.
819
820 You shouldn't use any of the characters @samp{|&;<>} in the string
821 @var{words} unless they are quoted; likewise for newline.  If you use
822 these characters unquoted, you will get the @code{WRDE_BADCHAR} error
823 code.  Don't use parentheses or braces unless they are quoted or part of
824 a word expansion construct.  If you use quotation characters @samp{'"`},
825 they should come in pairs that balance.
826
827 The results of word expansion are a sequence of words.  The function
828 @code{wordexp} allocates a string for each resulting word, then
829 allocates a vector of type @code{char **} to store the addresses of
830 these strings.  The last element of the vector is a null pointer.
831 This vector is called the @dfn{word vector}.
832
833 To return this vector, @code{wordexp} stores both its address and its
834 length (number of elements, not counting the terminating null pointer)
835 into @code{*@var{word-vector-ptr}}.
836
837 If @code{wordexp} succeeds, it returns 0.  Otherwise, it returns one
838 of these error codes:
839
840 @table @code
841 @comment wordexp.h
842 @comment POSIX.2
843 @item WRDE_BADCHAR
844 The input string @var{words} contains an unquoted invalid character such
845 as @samp{|}.
846
847 @comment wordexp.h
848 @comment POSIX.2
849 @item WRDE_BADVAL
850 The input string refers to an undefined shell variable, and you used the flag
851 @code{WRDE_UNDEF} to forbid such references.
852
853 @comment wordexp.h
854 @comment POSIX.2
855 @item WRDE_CMDSUB
856 The input string uses command substitution, and you used the flag
857 @code{WRDE_NOCMD} to forbid command substitution.
858
859 @comment wordexp.h
860 @comment POSIX.2
861 @item WRDE_NOSPACE
862 It was impossible to allocate memory to hold the result.  In this case,
863 @code{wordexp} can store part of the results---as much as it could
864 allocate room for.
865
866 @comment wordexp.h
867 @comment POSIX.2
868 @item WRDE_SYNTAX
869 There was a syntax error in the input string.  For example, an unmatched
870 quoting character is a syntax error.
871 @end table
872 @end deftypefun
873
874 @deftypefun void wordfree (wordexp_t *@var{word-vector-ptr})
875 Free the storage used for the word-strings and vector that
876 @code{*@var{word-vector-ptr}} points to.  This does not free the
877 structure @code{*@var{word-vector-ptr}} itself---only the other
878 structure pointed to by it.
879 @end deftypefun
880
881 @node Flags for Wordexp
882 @subsection Flags for Word Expansion
883
884 This section describes the flags that you can specify in the 
885 @var{flags} argument to @code{wordexp}.  Choose the flags you want,
886 and combine them with the C operator @code{|}.
887
888 @table @code
889 @comment wordexp.h
890 @comment POSIX.2
891 @item WRDE_APPEND
892 Append the words from this expansion to the vector of words produced by
893 previous calls to @code{wordexp}.  This way you can effectively expand
894 several words as if they were concatenated with spaces between them.
895
896 In order for appending to work, you must not modify the contents of the
897 word vector structure between calls to @code{wordexp}.  And, if you set
898 @code{WRDE_DOOFFS} in the first call to @code{wordexp}, you must also
899 set it when you append to the results.
900
901 @comment wordexp.h
902 @comment POSIX.2
903 @item WRDE_DOOFFS
904 Leave blank slots at the beginning of the vector of words.
905 The @code{we_offs} field says how many slots to leave.
906 The blank slots contain null pointers.
907
908 @comment wordexp.h
909 @comment POSIX.2
910 @item WRDE_NOCMD
911 Don't do command substitution; if the input requests command substitution,
912 report an error.
913
914 @comment wordexp.h
915 @comment POSIX.2
916 @item WRDE_REUSE
917 Reuse a word vector made by a previous call to @code{wordexp}.
918 Instead of allocating a new vector of words, this call to @code{wordexp}
919 will use the vector that already exists (making it larger if necessary).
920
921 @comment wordexp.h
922 @comment POSIX.2
923 @item WRDE_SHOWERR
924 Do show any error messages printed by commands run by command substitution.
925 More precisely, allow these commands to inherit the standard error output
926 stream of the current process.  By default, @code{wordexp} gives these
927 commands a standard error stream that discards all output.
928
929 @comment wordexp.h
930 @comment POSIX.2
931 @item WRDE_UNDEF
932 If the input refers to a shell variable that is not defined, report an
933 error.
934 @end table
935
936 @node Wordexp Example
937 @subsection @code{wordexp} Example
938
939 Here is an example of using @code{wordexp} to expand several strings
940 and use the results to run a shell command.  It also shows the use of
941 @code{WRDE_APPEND} to concatenate the expansions and of @code{wordfree}
942 to free the space allocated by @code{wordexp}.
943
944 @example
945 int
946 expand_and_execute (char *program, char *options)
947 @{
948   wordexp_t result;
949   int pid, status;
950   int i;
951   int fail;
952
953   /* @r{Expand the string for the program to run.}  */
954   fail = wordexp (program, &result, 0);
955   if (fail) @{
956     /* @r{If the error was @code{WRDE_NOSPACE},}
957        @r{then perhaps part of the result was allocated.}  */
958     if (fail == WRDE_NOSPACE)
959       wordfree (&result);
960     return -1;
961   @}
962
963   /* @r{Expand the strings specified for the arguments.}  */
964   for (i = 0; args[i]; i++) @{
965     fail = wordexp (options, &result, WRDE_APPEND);
966     if (fail) @{
967       wordfree (&result);
968       return -1;
969     @}
970   @}
971
972   pid = fork ();
973   if (pid == 0) @{
974     execv (result.we_wordv[0], result.we_wordv);
975     exit (EXIT_FAILURE);
976   @}
977   else if (pid < 0)
978     /* @r{The fork failed.  Report failure.}  */
979     status = -1;
980   else @{
981     /* @r{This is the parent process.  Wait for the child to complete.}  */
982     if (waitpid (pid, &status, 0) != pid)
983       status = -1;
984   @}
985
986   wordfree (&result);
987   return status;
988 @}
989 @end example
990
991 In practice, since @code{wordexp} is executed by running a subshell, it
992 would be faster to do this by concatenating the strings with spaces
993 between them and running that as a shell command using @samp{sh -c}.
994
995 @c No sense finishing this for here.
996 @ignore
997 @node Tilde Expansion
998 @subsection Details of Tilde Expansion
999
1000 It's a standard part of shell syntax that you can use @samp{~} at the
1001 beginning of a file name to stand for your own home directory.  You
1002 can use @samp{~@var{user}} to stand for @var{user}'s home directory.
1003
1004 @dfn{Tilde expansion} is the process of converting these abbreviations
1005 to the directory names that they stand for.
1006
1007 Tilde expansion applies to the @samp{~} plus all following characters up
1008 to whitespace or a slash.  It takes place only at the beginning of a
1009 word, and only if none of the characters to be transformed is quoted in
1010 any way.
1011
1012 Plain @samp{~} uses the value of the environment variable @code{HOME}
1013 as the proper home directory name.  @samp{~} followed by a user name
1014 uses @code{getpwname} to look up that user in the user database, and
1015 uses whatever directory is recorded there.  Thus, @samp{~} followed
1016 by your own name can give different results from plain @samp{~}, if
1017 the value of @code{HOME} is not really your home directory.
1018
1019 @node Variable Substitution
1020 @subsection Details of Variable Substitution
1021
1022 Part of ordinary shell syntax is the use of @samp{$@var{variable}} to
1023 substitute the value of a shell variable into a command.  This is called
1024 @dfn{variable substitution}, and it is one part of doing word expansion.
1025
1026 There are two basic ways you can write a variable reference for
1027 substitution:
1028
1029 @table @code
1030 @item $@{@var{variable}@}
1031 If you write braces around the variable name, then it is completely
1032 unambiguous where the variable name ends.  You can concatenate
1033 additional letters onto the end of the variable value by writing them
1034 immediately after the close brace.  For example, @samp{$@{foo@}s}
1035 expands into @samp{tractors}.
1036
1037 @item $@var{variable}
1038 If you do not put braces around the variable name, then the variable
1039 name consists of all the alphanumeric characters and underscores that
1040 follow the @samp{$}.  The next punctuation character ends the variable
1041 name.  Thus, @samp{$foo-bar} refers to the variable @code{foo} and expands
1042 into @samp{tractor-bar}.
1043 @end table
1044
1045 When you use braces, you can also use various constructs to modify the
1046 value that is substituted, or test it in various ways.
1047
1048 @table @code
1049 @item $@{@var{variable}:-@var{default}@}
1050 Substitute the value of @var{variable}, but if that is empty or
1051 undefined, use @var{default} instead.
1052
1053 @item $@{@var{variable}:=@var{default}@}
1054 Substitute the value of @var{variable}, but if that is empty or
1055 undefined, use @var{default} instead and set the variable to
1056 @var{default}.
1057
1058 @item $@{@var{variable}:?@var{message}@}
1059 If @var{variable} is defined and not empty, substitute its value.
1060
1061 Otherwise, print @var{message} as an error message on the standard error
1062 stream, and consider word expansion a failure.
1063
1064 @c ??? How does wordexp report such an error?
1065
1066 @item $@{@var{variable}:+@var{replacement}@}
1067 Substitute @var{replacement}, but only if @var{variable} is defined and
1068 nonempty.  Otherwise, substitute nothing for this construct.
1069 @end table
1070
1071 @table @code
1072 @item $@{#@var{variable}@}
1073 Substitute a numeral which expresses in base ten the number of
1074 characters in the value of @var{variable}.  @samp{$@{#foo@}} stands for
1075 @samp{7}, because @samp{tractor} is seven characters.
1076 @end table
1077
1078 These variants of variable substitution let you remove part of the
1079 variable's value before substituting it.  The @var{prefix} and 
1080 @var{suffix} are not mere strings; they are wildcard patterns, just
1081 like the patterns that you use to match multiple file names.  But
1082 in this context, they match against parts of the variable value
1083 rather than against file names.
1084
1085 @table @code
1086 @item $@{@var{variable}%%@var{suffix}@}
1087 Substitute the value of @var{variable}, but first discard from that
1088 variable any portion at the end that matches the pattern @var{suffix}.
1089
1090 If there is more than one alternative for how to match against
1091 @var{suffix}, this construct uses the longest possible match.
1092
1093 Thus, @samp{$@{foo%%r*@}} substitutes @samp{t}, because the largest
1094 match for @samp{r*} at the end of @samp{tractor} is @samp{ractor}.
1095
1096 @item $@{@var{variable}%@var{suffix}@}
1097 Substitute the value of @var{variable}, but first discard from that
1098 variable any portion at the end that matches the pattern @var{suffix}.
1099
1100 If there is more than one alternative for how to match against
1101 @var{suffix}, this construct uses the shortest possible alternative.
1102
1103 Thus, @samp{$@{foo%%r*@}} substitutes @samp{tracto}, because the shortest
1104 match for @samp{r*} at the end of @samp{tractor} is just @samp{r}.
1105
1106 @item $@{@var{variable}##@var{prefix}@}
1107 Substitute the value of @var{variable}, but first discard from that
1108 variable any portion at the beginning that matches the pattern @var{prefix}.
1109
1110 If there is more than one alternative for how to match against
1111 @var{prefix}, this construct uses the longest possible match.
1112
1113 Thus, @samp{$@{foo%%r*@}} substitutes @samp{t}, because the largest
1114 match for @samp{r*} at the end of @samp{tractor} is @samp{ractor}.
1115
1116 @item $@{@var{variable}#@var{prefix}@}
1117 Substitute the value of @var{variable}, but first discard from that
1118 variable any portion at the beginning that matches the pattern @var{prefix}.
1119
1120 If there is more than one alternative for how to match against
1121 @var{prefix}, this construct uses the shortest possible alternative.
1122
1123 Thus, @samp{$@{foo%%r*@}} substitutes @samp{tracto}, because the shortest
1124 match for @samp{r*} at the end of @samp{tractor} is just @samp{r}.
1125
1126 @end ignore