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