ftp_glob(3) C Library Calls ftp_glob(3)NAME
ftp_glob, ftp_globfree - find pathnames matching a pattern from an FTP
server
SYNOPSIS
#include <libfget.h>
int ftp_glob(FTP *ftp, const char *pattern, int flags, int
(*errfunc)(const char *, int), ftp_glob_t *pglob);
void ftp_globfree(ftp_glob_t *pglob);
VERSION
This man page documents version 1.3 of libfget.
DESCRIPTION
The ftp_glob() function searches for all the pathnames on the FTP
server associated with ftp that match pattern according to the rules
used by the shell.
The structure type ftp_glob_t 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 */
} ftp_glob_t;
The argument pattern is a pointer to a pathname pattern to be expanded.
ftp_glob() matches all accessible pathnames against the pattern and
creates a list of the pathnames that match. In order to have access to
a pathname, ftp_glob() requires search permission on every component of
a path except the last and read permission on each directory of any
filename component of pattern that contains any of the special charac‐
ters `*', `?', or `['.
The number of matched pathnames is stored in the gl_pathc field, and a
pointer to a list of pointers to pathnames in the 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
pglob. The ftp_glob() function allocates other space as needed,
including the memory pointed to by gl_pathv.
The argument flags is used to modify the behavior of ftp_glob(). The
value of flags is the bitwise inclusive OR of any of the following val‐
ues:
FTPGLOB_APPEND
Append pathnames generated to the ones from a previous call (or
calls) to ftp_glob(). The value of gl_pathc will be the total
matches found by this call and the previous call(s). The path‐
names are appended to, not merged with the pathnames returned by
the previous call(s). Between calls, the caller must not change
the setting of the FTPGLOB_DOOFFS flag, nor change the value of
gl_offs when FTPGLOB_DOOFFS is set, nor (obviously) call
ftp_globfree() for pglob.
FTPGLOB_DOOFFS
Make use of the gl_offs field. If this flag is set, gl_offs is
used to specify how many null pointers to prepend to the begin‐
ning of the gl_pathv field. In other words, gl_pathv will point
to gl_offs null pointers, followed by gl_pathc pathname point‐
ers, followed by a null pointer.
FTPGLOB_ERR
Causes ftp_glob() to return when it encounters a directory that
it cannot open or read. Ordinarily, ftp_glob() continues to
find matches.
FTPGLOB_MARK
Each pathname that is a directory that matches pattern has a
slash appended.
FTPGLOB_NOCHECK
If pattern does not match any pathname, then ftp_glob() returns
a list consisting of only pattern, with the number of total
pathnames set to 1, and the number of matched pathnames set to
0.
FTPGLOB_NOESCAPE
Normally, every occurrence of a backslash (`\') followed by a
character in pattern is replaced by that character. This is
done to negate any special meaning for the character. If the
FTPGLOB_NOESCAPE flag is set, a backslash character is treated
as an ordinary character.
FTPGLOB_NOSORT
By default, the pathnames are sorted in ascending ASCII order;
this flag prevents that sorting (speeding up ftp_glob()).
FTPGLOB_BRACE
Pre-process the pattern string to expand `{pat,pat,...}' strings
like csh(1). The pattern `{}' is left unexpanded for historical
reasons. (csh(1) does the same thing to ease typing of find(1)
patterns.)
FTPGLOB_MAGCHAR
Set by the ftp_glob() function if the pattern included globbing
characters. See the description of the usage of the gl_matchc
structure member for more details.
FTPGLOB_NOMAGIC
Is the same as FTPGLOB_NOCHECK, but it only appends the pattern
if it does not contain any of the special characters `*', `?',
or `['. FTPGLOB_NOMAGIC is provided to emulate the historic
csh(1) globbing behavior, and should probably not be used in
most applications.
If, during the search, a directory is encountered that cannot be opened
or read and errfunc is non-null, ftp_glob() calls (*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 errfunc. The error routine can suppress this
action by testing for ENOENT and ENOTDIR; however, the FTPGLOB_ERR flag
will still cause an immediate return when this happens.
If errfunc returns non-zero, ftp_glob() stops the scan and returns FTP‐
GLOB_ABORTED after setting gl_pathc and gl_pathv to reflect any paths
already matched. This also happens if an error is encountered and FTP‐
GLOB_ERR is set in flags, regardless of the return value of errfunc, if
called. If FTPGLOB_ERR is not set and either errfunc is NULL or
errfunc returns zero, the error is ignored.
The ftp_globfree() function frees any space associated with pglob from
a previous call(s) to ftp_glob().
RETURN VALUES
On successful completion, ftp_glob() returns 0. In addition the fields
of pglob contain the values described below:
gl_pathc
Contains the total number of matched pathnames so far. This
includes other matches from previous invocations of ftp_glob()
if FTPGLOB_APPEND was specified.
gl_matchc
Contains the number of matched pathnames in the current invoca‐
tion of ftp_glob().
gl_flags
Contains a copy of the flags parameter with the bit FTP‐
GLOB_MAGCHAR set if pattern contained any of the special charac‐
ters `*', `?', or `[', cleared if not.
gl_pathv
Contains a pointer to a null-terminated list of matched path‐
names. However, if gl_pathc is zero, the contents of gl_pathv
are undefined.
If ftp_glob() terminates due to an error, it sets errno and returns one
of the following non-zero constants:
FTPGLOB_NOSPACE
An attempt to allocate memory failed.
FTPGLOB_ABORTED
The scan was stopped because an error was encountered and either
FTPGLOB_ERR was set, or (*errfunc)() returned non-zero.
FTPGLOB_NOMATCH
The pattern did not match a pathname and FTPGLOB_NOCHECK was not
set.
The pglob fields gl_pathc and _gl_pathv are still set as specified
above.
EXAMPLES
The following code will find all matches for `*.c' and `*.h' on the FTP
server associated with ftp:
int i;
ftp_glob_t g;
ftp_glob(ftp, "*.c", 0, NULL, &g);
ftp_glob(ftp, "*.h", FTPGLOB_APPEND, NULL, &g);
for (i = 0; i < g.gl_pathc; i++)
printf("matching file: \"%s\"\n", g.gl_pathv[i]);
ERRORS
The ftp_glob() function may fail and set errno for any of the errors
specified for any of the ftp_stat(3), ftp_opendir(3), malloc(3), or
free(3) library calls.
BUGS
Patterns longer than MAXPATHLEN may cause unchecked errors.
SEE ALSOlibfget(3), glob(3)Feep Networks January 2004 ftp_glob(3)
