glob Subroutine

AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 1

glob Subroutine

Purpose

Generates path names.

Library

Standard C Library (libc.a)

Syntax

#include <glob.h>

int glob (Pattern, Flags, (Errfunc)(), Pglob)
const char *Pattern;
int Flags;
int *Errfunc (Epath, Eerrno)
const char *Epath;
int Eerrno;
glob_t *Pglob;

Description

The glob subroutine constructs a list of accessible files that match the Pattern parameter.

The glob subroutine matches all accessible path names against this pattern and develops a list of all matching path names. To have access to a path name, the glob subroutine requires search permission on every component of a path except the last, and read permission on each directory of any file name component of the Pattern parameter that contains any of the special characters * (asterisk), ? (question mark), or [ (left bracket). The glob subroutine stores the number of matched path names and a pointer to a list of pointers to path names in the Pglob parameter. The path names are in sort order, based on the setting of the LC_COLLATE category in the current locale. The first pointer after the last path name is a null character. If the pattern does not match any path names, the returned number of matched paths is zero.

Parameters

Pattern	Contains the file name pattern to compare against accessible path names.
Flags	Controls the customizable behavior of the glob subroutine. The Flags parameter controls the behavior of the glob subroutine. The Flags value is the bitwise inclusive OR of any of the following constants, which are defined in the glob.h file: GLOB_APPEND Appends path names located with this call to any path names previously located. If the GLOB_APPEND constant is not set, new path names overwrite previous entries in the Pglob array. The GLOB_APPEND constant should not be set on the first call to the glob subroutine. It may, however, be set on subsequent calls. The GLOB_APPEND flag can be used to append a new set of path names to those found in a previous call to the glob subroutine. If the GLOB_APPEND flag is specified in the Flags parameter, the following rules apply: If the application sets the GLOB_DOOFFS flag in the first call to the glob subroutine, it is also set in the second. The value of the Pglob parameter is not modified between the calls. If the application did not set the GLOB_DOOFFS flag in the first call to the glob subroutine, it is not set in the second. After the second call, the Pglob parameter points to a list containing the following: Zero or more null characters, as specified by the GLOB_DOOFFS flag. Pointers to the path names that were in the Pglob list before the call, in the same order as after the first call to the glob subroutine. Pointers to the new path names generated by the second call, in the specified order. The count returned in the Pglob parameter is the total number of path names from the two calls. The application should not modify the Pglob parameter between the two calls. It is the caller's responsibility to create the structure pointed to by the Pglob parameter. The glob subroutine allocates other space as needed. GLOB_DOOFFS Uses the gl_offs structure to specify the number of null pointers to add to the beginning of the gl_pathv component of the Pglob parameter. GLOB_ERR Causes the glob subroutine to return when it encounters a directory that it cannot open or read. If the GLOB_ERR flag is not set, the glob subroutine continues to find matches if it encounters a directory that it cannot open or read. GLOB_MARK Specifies that each path name that is a directory should have a `/` (slash) appended. GLOB_NOCHECK If the Pattern parameter does not match any path name, the glob subroutine returns a list consisting only of the Pattern parameter, and the number of matched patterns is one. GLOB_NOSORT Specifies that the list of path names need not be sorted. If the GLOB_NOSORT flag is not set, path names are collated according to the current locale. GLOB_QUOTE If the GLOB_QUOTE flag is set, a `\` (backslash) can be used to escape metacharacters.
Errfunc	Specifies an optional subroutine that, if specified, is called when the glob subroutine detects an error condition.
Pglob	Contains a pointer to a glob_t structure. The structure is allocated by the caller. The array of structures containing the file names matching the Pattern parameter are defined by the glob subroutine. The last entry is a null pointer.
Epath	Specifies the path that failed because a directory could not be opened or read.
Eerrno	Specifies the errno value of the failure indicated by the Epath parameter. This value is set by the opendir, readdir, or stat subroutines.

Return Values

On successful completion, the glob subroutine returns a value of 0. The Pglob parameter returns the number of matched path names and a pointer to a null-terminated list of matched and sorted path names. If the number of matched path names in the Pglob parameter is zero, the pointer in the Pglob parameter is undefined.

Error Codes

If the glob subroutine terminates due to an error, it returns one of the nonzero constants below. These are defined in the glob.h file. In this case, the Pglob values are still set as defined in the Return Values section.

GLOB_ABORTED	Indicates the scan was stopped because the GLOB_ERROR flag was set or the subroutine specified by the errfunc parameter returned a nonzero value.
GLOB_NOSPACE	Indicates a failed attempt to allocate memory.

If, during the search, a directory is encountered that cannot be opened or read and the Errfunc parameter is not a null value, the glob subroutine calls the subroutine specified by the errfunc parameter with two arguments:

The Epath parameter specifies the path that failed.
The Eerrno parameter specifies the value of the errno global variable from the failure, as set by the opendir, readdir, or stat subroutine.

If the subroutine specified by the Errfunc parameter is called and returns nonzero, or if the GLOB_ERR flag is set in the Flags parameter, the glob subroutine stops the scan and returns GLOB_ABORTED after setting the Pglob parameter to reflect the paths already scanned. If GLOB_ERR is not set and either the Errfunc parameter is null or *errfunc returns zero, the error is ignored.

The Pglob parameter has meaning even if the glob subroutine fails. Therefore, the glob subroutine can report partial results in the event of an error. However, if the number of matched path names is 0, the pointer in the Pglob parameter is unspecified even if the glob subroutine did not return an error.

Examples

The GLOB_NOCHECK flag can be used with an application to expand any path name using wildcard characters. However, the GLOB_NOCHECK flag treats the pattern as just a string by default. The sh command can use this facility for option parameters, for example.

The GLOB_DOOFFS flag can be used by applications that build an argument list for use with the execv, execve, or execvp subroutine. For example, an application needs to do the equivalent of ls -l *.c, but for some reason cannot. The application could still obtain approximately the same result using the sequence:

globbuf.gl_offs = 2;
glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
globbuf.gl_pathv[0] = "ls";
globbuf.gl_pathv[1] ="-l";
execvp ("ls", &globbuf.gl_pathv[0]);

Using the same example, ls -l *.c *.h could be approximated using the GLOB_APPEND flag as follows:

globbuf.gl_offs = 2;
glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
glob ("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf);

The new path names generated by a subsequent call with the GLOB_APPEND flag set are not sorted together with the previous path names. This is the same way the shell handles path name expansion when multiple expansions are done on a command line.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The exec: execl, execv, execle, execve, execlp, execvp, or exect subroutine, fnmatch subroutine, opendir, readdir, telldir, seekdir, rewinddir, or closedir subroutine, statx, stat, lstat, fstatx, fstat, fullstat, or ffullstat subroutine.

The ls command.

National Language Support Overview for Programming in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.