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