PC Extra Super CD 1998 January/PCPLUS131.iso/DJGPP/V2/DJLSR201.ZIP/src/libc/posix/glob/glob.txh

Text File | 1996-08-31 | 6.5 KB | 215 lines

@node glob, shell
@subheading Syntax

@example
#include <glob.h>

int  glob(const char *pattern, int flags,
          int (*errfunc)(const char *epath, int eerrno), glob_t *pglob);
@end example

@subheading Description

This function expands a filename wildcard which is passed as
@var{pattern}.  The pattern may include these special characters:

@table @code

@item *

Matches zero of more characters.

@item ?

Matches exactly one character (any character).

@item [...]

Matches one character from a group of characters.  If the first
character is @code{!}, matches any character @emph{not} in the group.  A
group is defined as a list of characters between the brackets,
e.g. @code{[dkl_]}, or by two characters separated by @code{-} to
indicate all characters between and including these two.  For example,
@code{[a-d]} matches @code{a}, @code{b}, @code{c}, or @code{d}, and
@code{[!a-zA-Z0-9]} matches any character that is not alphanumeric.

@item ...

Matches all the subdirectories, recursively (VMS aficionados,
rejoice!).

@item \

Causes the next character to not be treated as special.  For example,
@code{\[} matches a literal @samp{[}.  If @var{flags} includes
@code{GLOB_NOESCAPE}, this quoting is disabled and @samp{\} is handled
as a simple character.

@end table

The variable @var{flags} controls certain options of the expansion
process.  Possible values for @var{_flags} are as follows:

@table @code

@item GLOB_APPEND

Append the matches to those already present in the array
@code{pglob->gl_pathv}.  By default, @code{glob} discards all previous
contents of @code{pglob->gl_pathv} and allocates a new memory block for
it.  If you use @code{GLOB_APPEND}, @code{pglob} should point to a
structure returned by a previous call to @code{glob}.

@item GLOB_DOOFFS

Skip @code{pglob->gl_offs} entries in @code{gl_pathv} and put new
matches after that point.  By default, @code{glob} puts the new matches
beginning at @code{pglob->gl_pathv[0]}.  You can use this flag both with
@code{GLOB_APPEND} (in which case the new matches will be put after the
first @code{pglob->gl_offs} matches from previous call to @code{glob}),
or without it (in which case the first @code{pglob->gl_offs} entries in
@code{pglob->gl_pathv} will be filled by @code{NULL} pointers).

@item GLOB_ERR

Stop when an unreadable directory is encountered and call user-defined
function @var{errfunc}.  This cannot happen under DOS (and thus
@var{errfunc} is never used).

@item GLOB_MARK

Append a slash to each pathname that is a directory.

@item GLOB_NOCHECK

If no matches are found, return the pattern itself as the only match.
By default, @code{glob} doesn't change @code{pglob} if no matches are
found.

@item GLOB_NOESCAPE

Disable blackslash as an escape character.  By default, backslash quotes
special meta-characters in wildcards described above.

@item GLOB_NOSORT

Do not sort the returned list.  By default, the list is sorted
alphabetically.  This flag causes the files to be returned in the order
they were found in the directory.

@end table

Given the pattern and the flags, @code{glob} expands the pattern and
returns a list of files that match the pattern in a structure a pointer
to which is passed via @var{pglob}.  This structure is like this:

@example
typedef struct @{
  size_t gl_pathc;
  char **gl_pathv;
  size_t gl_offs;
@} glob_t;
@end example

In the structure, the @code{gl_pathc} field holds the number of
filenames in @code{gl_pathv} list; this includes the filenames produced
by this call, plus any previous filenames if @code{GLOB_APPEND} or
@code{GLOB_DOOFFS} were set in @var{flags}.  The list of matches is
returned as an array of pointers to the filenames; @code{gl_pathv} holds
the address of the array.  Thus, the filenames which match the pattern
can be accessed as @code{gl_pathv[0]}, @code{gl_pathv[1]}, etc.  If
@code{GLOB_DOOFFS} was set in @var{flags}, the new matches begin at
offset given by @code{gl_offs}.

@subheading Return Value

Zero on success, or one of these codes:

@table @code

@item GLOB_ABORTED

Not used in DJGPP implementation.

@item GLOB_NOMATCH

No files matched the given pattern.

@item GLOB_NOSPACE

Not enough memory to accomodate expanded filenames.

@item GLOB_ERR

Never happens on MSDOS, see above.

@end table

@subheading Notes

@code{glob} will not match names of volume labels.

On MSDOS, filenames are always matched case-insensitively.  On
filesystems that preserve letter-case in filenames (such as Windows 9x),
matches are case-insensitive unless the pattern includes uppercase
characters.

On MSDOS, the list of expanded filenames will be returned in lower case,
if all the characters of the pattern (except those between brackets
[...]) are lower-case; if some of them are upper-case, the expanded
filenames will be also in upper case.  On filesystems that preserve
letter-case in filenames, long filenames are returned as they are found
in the directory entry; DOS-style 8+3 filenames are returned as on MSDOS
(in lower case if the pattern doesn't include any upper-case letters, in
upper case otherwise).

When the environment variable @samp{LFN} is set to @kbd{n}, @code{glob}
behaves on Windows 9x exactly as it does on MSDOS.

Setting the environment variable @samp{FNCASE} to @kbd{y}, or setting
the @code{_CRT0_FLAG_PRESERVE_FILENAME_CASE} bit in the
@code{_crt0_startup_flags} variable (@pxref{_crt0_startup_flags})
suppresses any letter-case conversions in filenames and forces
case-sensitive filename matching.  @xref{_preserve_fncase}.

@subheading Example

@example

#include <stdlib.h>
#include <string.h>
#include <glob.h>

/* Convert a wildcard pattern into a list of blank-separated
   filenames which match the wildcard.  */

char * glob_pattern(char *wildcard)
@{
  char *gfilename;
  size_t cnt, length;
  glob_t glob_results;
  char **p;

  glob(wildcard, GLOB_NOCHECK, 0, &glob_results);

  /* How much space do we need?  */
  for (p = glob_results.gl_pathv, cnt = glob_results.gl_pathc;
       cnt; p++, cnt--)
    length += strlen(*p) + 1;

  /* Allocate the space and generate the list.  */
  gfilename = (char *) calloc(length, sizeof(char));
  for (p = glob_results.gl_pathv, cnt = glob_results.gl_pathc;
       cnt; p++, cnt--)
    @{
      strcat(gfilename, *p);
      if (cnt > 1)
        strcat(gfilename, " ");
    @}

  globfree(&glob_results);
  return gfilename;
@}

@end example