Generates path names.
Standard C Library (libc.a)
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.
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:
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:
It is the caller's responsibility to create the structure pointed to by the Pglob parameter. The glob subroutine allocates other space as needed.
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.
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.
| Item | Description |
|---|---|
| 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:
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.
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.