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. Note: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 Note:Accessing
Directories, and Note: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'.