More Flags for Globbing - The GNU C Library

Previous: Flags for Globbing, Up: Globbing

#### 10.2.3 More Flags for Globbing

Beside the flags described in the last section, the GNU implementation of `glob` allows a few more flags which are also defined in the `glob.h` file. Some of the extensions implement functionality which is available in modern shell implementations.

`GLOB_PERIOD`
  The `.` character (period) is treated special. It cannot be matched by wildcards. See Wildcard Matching, `FNM_PERIOD`.
`GLOB_MAGCHAR`
  The `GLOB_MAGCHAR` value is not to be given to `glob` in the flags parameter. Instead, `glob` sets this bit in the gl_flags element of the glob_t structure provided as the result if the pattern used for matching contains any wildcard character.
`GLOB_ALTDIRFUNC`
  Instead of the using the using the normal functions for accessing the filesystem the `glob` implementation uses the user-supplied functions specified in the structure pointed to by pglob parameter. For more information about the functions refer to the sections about directory handling see Accessing Directories, and Reading Attributes.
`GLOB_BRACE`
  If this flag is given the handling of braces in the pattern is changed. It is now required that braces appear correctly grouped. I.e., for each opening brace there must be a closing one. Braces can be used recursively. So it is possible to define one brace expression in another one. It is important to note that the range of each brace expression is completely contained in the outer brace expression (if there is one).

  The string between the matching braces is separated into single expressions by splitting at `,` (comma) characters. The commas themselves are discarded. Please note what we said above about recursive brace expressions. The commas used to separate the subexpressions must be at the same level. Commas in brace subexpressions are not matched. They are used during expansion of the brace expression of the deeper level. The example below shows this

                glob ("{foo/{,bar,biz},baz}", GLOB_BRACE, NULL, &result)

  is equivalent to the sequence

                glob ("foo/", GLOB_BRACE, NULL, &result)
                glob ("foo/bar", GLOB_BRACE|GLOB_APPEND, NULL, &result)
                glob ("foo/biz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
                glob ("baz", GLOB_BRACE|GLOB_APPEND, NULL, &result)

  if we leave aside error handling.

`GLOB_NOMAGIC`
  If the pattern contains no wildcard constructs (it is a literal file name), return it as the sole “matching” word, even if no file exists by that name.
`GLOB_TILDE`
  If this flag is used the character `~` (tilde) is handled special if it appears at the beginning of the pattern. Instead of being taken verbatim it is used to represent the home directory of a known user.

  If `~` is the only character in pattern or it is followed by a `/` (slash), the home directory of the process owner is substituted. Using `getlogin` and `getpwnam` the information is read from the system databases. As an example take user `bart` with his home directory at `/home/bart`. For him a call like

                glob ("~/bin/*", GLOB_TILDE, NULL, &result)

  would return the contents of the directory `/home/bart/bin`. Instead of referring to the own home directory it is also possible to name the home directory of other users. To do so one has to append the user name after the tilde character. So the contents of user `homer`'s `bin` directory can be retrieved by

                glob ("~homer/bin/*", GLOB_TILDE, NULL, &result)

  If the user name is not valid or the home directory cannot be determined for some reason the pattern is left untouched and itself used as the result. I.e., if in the last example `home` is not available the tilde expansion yields to `"~homer/bin/*"` and `glob` is not looking for a directory named `~homer`.

  This functionality is equivalent to what is available in C-shells if the `nonomatch` flag is set.

`GLOB_TILDE_CHECK`
  If this flag is used `glob` behaves like as if `GLOB_TILDE` is given. The only difference is that if the user name is not available or the home directory cannot be determined for other reasons this leads to an error. `glob` will return `GLOB_NOMATCH` instead of using the pattern itself as the name.

  This functionality is equivalent to what is available in C-shells if `nonomatch` flag is not set.

`GLOB_ONLYDIR`
  If this flag is used the globbing function takes this as a hint that the caller is only interested in directories matching the pattern. If the information about the type of the file is easily available non-directories will be rejected but no extra work will be done to determine the information for each file. I.e., the caller must still be able to filter directories out.

  This functionality is only available with the GNU `glob` implementation. It is mainly used internally to increase the performance but might be useful for a user as well and therefore is documented here.

Calling `glob` will in most cases allocate resources which are used to represent the result of the function call. If the same object of type `glob_t` is used in multiple call to `glob` the resources are freed or reused so that no leaks appear. But this does not include the time when all `glob` calls are done.

— Function: void globfree (glob_t *pglob)

> The `globfree` function frees all resources allocated by previous calls to `glob` associated with the object pointed to by pglob. This function should be called whenever the currently used `glob_t` typed object isn't used anymore.

— Function: void globfree64 (glob64_t *pglob)

> This function is equivalent to `globfree` but it frees records of type `glob64_t` which were allocated by `glob64`.