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