DragonFly On-Line Manual Pages
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
characters `*', `?', 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
values:
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
pathnames 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
beginning of the gl_pathv field. In other words, gl_pathv will
point to gl_offs null pointers, followed by gl_pathc pathname
pointers, 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
FTPGLOB_ABORTED after setting gl_pathc and gl_pathv to reflect any
paths already matched. This also happens if an error is encountered
and FTPGLOB_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
invocation of ftp_glob().
gl_flags
Contains a copy of the flags parameter with the bit
FTPGLOB_MAGCHAR set if pattern contained any of the special
characters `*', `?', or `[', cleared if not.
gl_pathv
Contains a pointer to a null-terminated list of matched
pathnames. 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 ALSO
libfget(3), glob(3)
Feep Networks January 2004 ftp_glob(3)