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