glob(S)

glob, globfree -- generate pathnames matching a pattern

Syntax

cc . . . -lc

#include <glob.h>

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

void globfree(glob_t *pglob);

Description

glob(S) expands the pathname pattern pattern to a list of accessible matching pathnames. The pathname pattern is not a regular expression, but rather is in the form used in filename generation in the shell, like ``file*'', ``file[0-9]'', etc. See sh(C) for a brief summary on filename generation.

glob( ) matches all accessible pathnames against this pattern and generates a list of all matching pathnames. A pointer to this list of matching pathnames, together with the number of generated pathnames, are stored by glob( ) on its return. The structure of type glob_t, pointed to by pglob, is used to store these information.

A pathname is accessible if glob( ) has search permission on every component of the pathname except the last one, and if glob( ) has read permission on each directory of a filename component in pattern when any of the following special characters is part of that component:

    *     ?     [

The structure type glob_t is defined in the header file <glob.h> and includes at least the following members:

Member Type Member Name Description

size_t gl_pathc Number of matched pathnames

char ** gl_pathv Pointer to a list of matched pathnames

size_t gl_offs Number of pointers to reserve at

the beginning of gl_pathv array

The structure pointed to by pglob must be created first, glob( ) then allocates other space as needed, like the memory pointed to by gl_pathv.

globfree(S) frees all memory associated with pglob, but does not free the pglob structure itself.

The default behavior of glob( ) can be modified by the flags argument, formed from a bitwise inclusive OR of zero or more of the following flags defined in <glob.h>:

GLOB_APPEND: Append pathnames generated in this call to the list of pathnames generated from previous calls to glob( ).
GLOB_DOOFFS: The number of null pointers to be inserted to the beginning of pglob->gl_pathv is pglob->gl_offs. In other words, in the list of pointers pglob->gl_pathv pointed to, the first pglob->gl_offs pointers are null, the next pglob->gl_pathc pointers are pathname pointers, and the final pointer is a null pointer again.
GLOB_ERR: If glob( ) cannot open or read a directory during its search, return immediately. The default behavior is to continue to find matches.
GLOB_MARK: Append a slash to each matched pathname if it is a directory.
GLOB_NOCHECK: If no pathname matched by pattern, glob( ) returns in pglob->gl_pathv a list consisting of only pattern and sets pglob->gl_pathc to 1.
GLOB_NOESCAPE: Disable backslash escaping.
GLOB_NOSORT: The default behavior is to sort the matching pathnames according to the current LC_COLLATE settings. If this flag is set, the pathnames are not sorted.

To append a new set of pathnames to those found previously, make repeated calls to glob( ), with the same value of pglob and without intervening calls to globfree( ). The following rules apply when two or more calls to glob( ) are made to append new pathnames:

The first call in sequence must not set GLOB_APPEND. All subsequent calls must have this flag set.
Either all the calls set the GLOB_DOOFFS flag or none of the calls can set it.
The list of pointers pointed to by pglob->gl_pathv contains the following after the second call:

a)
pglob->gl_offs null pointers if GLOB_DOOFFS is set

b)
pointers to all pathnames generated before the call, without any change to their ordering

c)
pointers to the new pathnames generated by the latest call, in the sort order if GLOB_NOSORT is not set
The pathname number returned in pglob->gl_pathc is updated to the total number of pathnames from all previous calls, including the latest one.
The application can change any of the fields in the pglob structure between calls to glob( ), or between calls to glob( ) and globfree( ). But when glob( ) is called the next time with the GLOB_APPEND flag set and using the same pglob value, or when globfree( ) is called the next time to free memories associated with pglob, those changed fields must be reset to their original values as immediately after glob( ) returned.

If the GLOB_ERR flag is set, glob( ) stops the search immediately when it cannot open or cannot read a directory during its search. After setting gl_pathc and gl_pathv in pglob to reflect the paths already scanned, it returns GLOB_ABORTED.

If the GLOB_ERR flag is not set and if errfunc is not a null pointer, glob( ) calls (*errfunc)() when it cannot open or cannot read a directory during its search. Two arguments are passed to (*errfunc)():

A pointer to the failed path, epath.
The value of errno from the failure, eerrno, set by opendir(S), readdir(S) or stat(S) routines.

If (*errfunc)() returns non-zero, glob( ) also stops the search and returns GLOB_ABORTED after setting gl_pathc and gl_pathv.

Otherwise, i.e., if GLOB_ERR is not set, and if either errfunc is a null pointer or (*errfunc)() returns zero, the error is ignored.

Note that gl_pathc and gl_pathv contain partial results even if glob( ) fails. However, if gl_pathc is zero, the content of gl_pathv is meaningless even if glob( ) did not return an error.

If wildcards are used in pattern to expand a pathname but otherwise the pattern should be treated simply as a string, the GLOB_NOCHECK flag could be used. For example, the sh utility might use this for option-arguments.

When pathnames are appended to previously generated pathnames, the new pathnames are not sorted together with pathnames generated in previous calls. This mirrors the shell's handling of pathname expansion when multiple expansions are done on a command line.

As an SCO OpenServer specific feature, glob( ) also examines its pattern argument and returns GLOB_BADPAT if it detects an invalid pathname pattern. For example, the pattern [[:alpha]] causes glob( ) to return GLOB_BADPAT because of the missing colon (:) after alpha. To use this feature and still retain XPG4 compliance for an application program, conditionally include the code that detects GLOB_BADPAT, as in:

           switch (glob(pattern, flags, NULL, &globbuf)) {
           case 0:
                   /* Code for match */
                   break;
           case GLOB_NOMATCH:
                   /* Code for no match */
                   break;
           .
           .
           .
   #ifdef GLOB_BADPAT
           case GLOB_BADPAT:
                   /* Bad pattern error handling */
                   break;
   #endif /* GLOB_BADPAT */
           .
           .
           .
           }

The rules used in expanding the pathname pattern are defined in the X/Open CAE Specification, Commands and Utilities, Issue 4, 1992 (XCU), Section 2.13, Pattern Matching Notation. Optional support for rule 3 in the XCU specification, Section 2.13.3, Patterns used for Filename Expansion, is enabled through the flag GLOB_NOCHECK.

Return values

Upon successful completion, glob( ) returns zero. The number of matched pathnames is returned in pglob->gl_pathc, and pglob->gl_pathv points to a sorted list of matched pathnames. The pointer immediately after the last pathname is a null pointer. The flags GLOB_NOCHECK and GLOB_NOSORT can modify the values returned in the structure *pglob.

When no match is found, glob( ) returns GLOB_NOMATCH, gl_pathc is zero and the content of gl_pathv is meaningless.

glob( ) returns GLOB_NOSYS and sets errno to ENOSYS. globfree( ) returns and sets errno to ENOSYS.

Diagnostics

If glob( ) terminates due to an error, it returns one of the following non-zero constants defined in <glob.h>. The structure members pglob->gl_pathc and pglob->gl_pathv are still set as described above, and may contain partial results.

GLOB_ABORTED: The search was aborted because either GLOB_ERR is set or (*errfunc)() returned non-zero.
GLOB_NOMATCH: The pattern does not match any accessible pathname and GLOB_NOCHECK was not set in flags.
GLOB_NOSPACE: Cannot allocate memory.
GLOB_NOSYS: The routine is not supported on this implementation.
GLOB_BADPAT: Invalid pathname pattern in pattern. This is SCO OpenServer specific.

Examples

Filename generation on a command line is performed by the shell, and this routine is not provided for utilities to replace this shell functionality. Instead, applications may use this routine to do pathname expansion on strings obtained from sources other than the command line, such as patterns entered interactively by a user or read from a data file. Suppose an application is given two strings "*.c" and "*.h" and needs to list filenames matching these two patterns,

ls -l *.c *.h

but for some reason,

   system("ls -l *.c *.h");

is not acceptable. This can be approximately simulated by using GLOB_DOOFFS and GLOB_APPEND as follows:

    ...
   strcpy(str1, "*.c");  /* or obtain the strings from standard input */
   strcpy(str2, "*.h");      
    ...
   globbuf.gl_offs = 2;  /* reserve slots for "ls" and "-l" */
   glob(str1, GLOB_DOOFFS,             NULL, &globbuf);
   glob(str2, GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf);
   globbuf.gl_pathv[0] = "ls";
   globbuf.gl_pathv[1] = "-l";
   execvp("ls", &globbuf.gl_pathv[0]);   /* simulate "ls -l *.c *.h" */

Notes

Use fnmatch(S) to examine if a pathname matches a given pattern.

Warning

The return value GLOB_BADPAT is SCO OpenServer specific and may not be supported in future releases. Its use without proper caution could make an application code non-XPG4 compliant.

Standards conformance

glob( ) and globfree( ) are conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992.

Member Type	Member Name	Description
size_t	`gl_pathc`	Number of matched pathnames
char **	`gl_pathv`	Pointer to a list of matched pathnames
size_t	`gl_offs`	Number of pointers to reserve at
		the beginning of `gl_pathv` array