Copyright (C) 2000-2012 |
Manpages GLOBSection: C Library Functions (3)Index Return to Main Contents BSD mandoc NAMEglob globfree - generate pathnames matching a patternLIBRARYLb libcSYNOPSISFd #include <glob.h> Ft int Fn glob const char *pattern int flags const int (*errfunc)(const char *, int) glob_t *pglob Ft void Fn globfree glob_t *pglobDESCRIPTIONThe Fn glob function is a pathname generator that implements the rules for file name pattern matching used by the shell.The include file glob.h defines the structure type Fa glob_t , which contains at least the following fields: typedef struct { int gl_pathc; /* count of total paths so far */ int gl_matchc; /* count of paths matching pattern */ int gl_offs; /* reserved at beginning of gl_pathv */ int gl_flags; /* returned flags */ char **gl_pathv; /* list of paths matching pattern */ } glob_t; The argument Fa pattern is a pointer to a pathname pattern to be expanded. The Fn glob argument matches all accessible pathnames against the pattern and creates a list of the pathnames that match. In order to have access to a pathname, Fn glob requires search permission on every component of a path except the last and read permission on each directory of any filename component of Fa pattern that contains any of the special characters `*' , `?' or `[' The Fn glob argument stores the number of matched pathnames into the Fa gl_pathc field, and a pointer to a list of pointers to pathnames into the Fa gl_pathv field. The first pointer after the last pathname is NULL If the pattern does not match any pathnames, the returned number of matched paths is set to zero. It is the caller's responsibility to create the structure pointed to by Fa pglob . The Fn glob function allocates other space as needed, including the memory pointed to by Fa gl_pathv . The argument Fa flags is used to modify the behavior of Fn glob . The value of Fa flags is the bitwise inclusive OR of any of the following values defined in glob.h
The following values may also be included in Fa flags , however, they are non-standard extensions to St -p1003.2 .
If, during the search, a directory is encountered that cannot be opened or read and Fa errfunc is non- NULL Fn glob calls Fa (*errfunc)(path, errno) . This may be unintuitive: a pattern like `*/Makefile' will try to stat(2) `foo/Makefile' even if `foo' is not a directory, resulting in a call to Fa errfunc . The error routine can suppress this action by testing for ENOENT and ENOTDIR however, the GLOB_ERR flag will still cause an immediate return when this happens. If Fa errfunc returns non-zero, Fn glob stops the scan and returns GLOB_ABORTED after setting Fa gl_pathc and Fa gl_pathv to reflect any paths already matched. This also happens if an error is encountered and GLOB_ERR is set in Fa flags , regardless of the return value of Fa errfunc , if called. If GLOB_ERR is not set and either Fa errfunc is NULL or Fa errfunc returns zero, the error is ignored. The Fn globfree function frees any space associated with Fa pglob from a previous call(s) to Fn glob . The historical GLOB_QUOTE flag is no longer supported. Per St -p1003.2-92 , backslash escaping of special characters is the default behaviour; it may be disabled by specifying the GLOB_NOESCAPE flag. RETURN VALUESOn successful completion, Fn glob returns zero. In addition the fields of Fa pglob contain the values described below:
If Fn glob terminates due to an error, it sets errno and returns one of the following non-zero constants, which are defined in the include file Aq Pa glob.h :
The historical GLOB_ABEND return constant is no longer supported. Portable applications should use the GLOB_ABORTED constant instead. The arguments Fa pglob->gl_pathc and Fa pglob->gl_pathv are still set as specified above. ENVIRONMENT
EXAMPLEA rough equivalent of `ls' -l *.c *.h can be obtained with the following code:glob_t g; g.gl_offs = 2; glob("*.c", GLOB_DOOFFS, NULL, &g); glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); g.gl_pathv[0] = "ls"; g.gl_pathv[1] = "-l"; execvp("ls", g.gl_pathv); SEE ALSOsh(1), fnmatch(3), regexp(3)STANDARDSThe Fn glob function is expected to be St -p1003.2 compatible with the exception that the flags GLOB_ALTDIRFUNC, GLOB_BRACE GLOB_MAGCHAR, GLOB_NOMAGIC, GLOB_TILDE, and GLOB_LIMIT and the fields Fa gl_matchc and Fa gl_flags should not be used by applications striving for strict POSIX conformance.HISTORYThe Fn glob and Fn globfree functions first appeared in BSD 4.4BUGSPatterns longer than MAXPATHLEN may cause unchecked errors.The Fn glob function may fail and set errno for any of the errors specified for the library routines stat(2), closedir(3), opendir(3), readdir(3), malloc(3), and free(3).
IndexThis document was created by man2html, using the manual pages. Time: 02:16:11 GMT, May 05, 2024 |