*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> glob (3g)              


glob(3G)							      glob(3G)

NAME    [Toc]    [Back]

     glob - generate pathnames matching	a pattern

SYNOPSIS    [Toc]    [Back]

     #include <glob.h>

     int glob(const char *pattern, int flags,
	 int(*errfunc)(const char *epath, int eerrno),
	     glob_t *pglob);

     void globfree(glob_t *pglob);

DESCRIPTION    [Toc]    [Back]

     The structure type	glob_t is defined in the header	<glob.h> and includes
     at	least the following members:

     MemberType	 MemberName Description
     size_t	 gl_offs    Slots to reserve at	start of gl_pathv.
     char **	 gl_pathv   Pointer to list of matched pathnames.
     size_t	 gl_pathc   Count of paths matched by pattern.

     The argument pattern is a pointer to a pathname pattern to	be expanded.
     The glob function matches all accessible pathnames	against	this pattern
     and develops a list of all	pathnames that match.  In order	to have	access
     to	a pathname, 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 following

	  *	?      [

     The glob function stores the number of matched pathnames into
     pglob->gl_pathc and a pointer to a	list of	pointers to pathnames into
     pglob->gl_pathv. The pathnames are	in sort	order as defined by the
     current setting of	the LC_COLLATE category.  The first pointer after the
     last pathname is a	null pointer.  If the pattern does not match any
     pathnames,	the returned number of matched paths is	set to zero, and the
     contents of pglob->gl_pathv are undetermined.

     It	is the caller's	responsibility to create the structure pointed to by
     glob.  glob allocates other space as needed, including the	memory pointed
     to	by gl_pathv. The globfree function frees any space associated with
     glob from a previous call to glob.

     The flags argument	is used	to control the behaviour of glob.  The value
     of	flags is a bitwise inclusive OR	of zero	or more	of the following
     constants,	which are defined in the header	<glob.h>:


	  Append pathnames generated to	the ones from a	previous call to glob.

									Page 1

glob(3G)							      glob(3G)


	  Make use of pglob->gl_offs. If this flag is set, pglob->gl_offs is
	  used to specify how many null	pointers to add	to the beginning of
	  pglob->gl_pathv. In other words, pglob->gl_pathv will	point to
	  pglob->gl_offs null pointers,	followed by pglob->gl_pathc pathname
	  pointers, followed by	a null pointer.


	  Causes glob to return	when it	encounters a directory that it cannot
	  open or read.	 Ordinarily, glob continues to find matches.


	  Each pathname	that is	a directory that matches pattern has a slash


	  If pattern does not match any	pathname, then glob returns a list
	  consisting of	only pattern, and the number of	matched	pathnames is
	  one (1).


	  Disable backslash escaping.


	  Ordinarily, glob sorts the matching pathnames	according to the
	  current setting of the LC_COLLATE category.  When this flag is used
	  the order of pathnames returned is unspecified.


	  Limit	the amount of memory used by matches to	{ARG_MAX} [see
	  sysconf(2)].	This option should be set for programs that can	be
	  coerced to a denial of service attack	via patterns that expand to a
	  very large number of matches.

     The GLOB_APPEND flag can be used to append	a new set of pathnames to
     those found in a previous call to glob.  The following rules apply	when
     two or more calls to glob are made	with the same value of pglob and
     without intervening calls to globfree:

       The first such call must	not set	GLOB_APPEND.  All subsequent calls
       must set	it.

       All the calls must set GLOB_DOOFFS, or all must not set it.

       After the second	call, pglob->gl_pathv points to	a list containing the

									Page 2

glob(3G)							      glob(3G)


	  Zero or more null pointers, as specified by GLOB_DOOFFS and

	  Pointers to the pathnames that were in the pglob->gl_pathv list
	  before the call, in the same order as	before.

	  Pointers to the new pathnames	generated by the second	call, in the
	  specified order.

       The count returned in pglob->gl_pathc will be the total number of
       pathnames from the two calls.

       The application can change any of the fields after a call to glob.  If
       it does,	it must	reset them to the original value before	a subsequent
       call, using the same pglob value, to globfree or	glob with the
       GLOB_APPEND flag.

     If, during	the search, a directory	is encountered that cannot be opened
     or	read and errfunc is not	a null pointer,	glob calls (*errfunc())	with
     two arguments:

       The epath argument is a pointer to the path that	failed.

       The eerrno argument is the value	of errno from that failure, as set by
       opendir(), readdir() or stat().	(Other values may be used to report
       other errors not	explicitly documented for those	functions.)

     The following constants are defined as error return values	for glob:


	  The scan was stopped because GLOB_ERR	was set	or (*errfunc())
	  returned non-zero.


	  The pattern does not match any existing pathname, and	GLOB_NOCHECK
	  was not set in flags.


	  An attempt to	allocate memory	failed,	or if errno was	0, GLOB_LIMIT
	  was specified	in the flags and the amount of memory required for the
	  matched patterns exceeded {ARG_MAX}.

     If	(*errfunc()) is	called and returns non-zero or if the GLOB_ERR flag is
     set in flags, glob	stops the scan and returns GLOB_ABORTED	after setting
     gl_pathv in pglob to reflect the paths already scanned.  If GLOB_ERR is
     not set and either	errfunc	is a null pointer or (*errfunc()) returns
     zero, the error is	ignored.

									Page 3

glob(3G)							      glob(3G)

RETURN VALUE    [Toc]    [Back]

     On	successful completion, glob returns zero.  The argument
     pglob->gl_pathc returns the number	of matched pathnames and the argument
     pglob->gl_pathv contains a	pointer	to a null-terminated list of matched
     and sorted	pathnames.  However, if	pglob->gl_pathc	is zero, the contents
     of	pglob->gl_pathv	is undefined.

     The globfree function returns no value.

     If	glob terminates	due to an error, it returns one	of the non-zero
     constants defined in <glob.h>.  The arguments pglob->gl_pathc and
     pglob->gl_pathv are still set as defined above.

EXAMPLES    [Toc]    [Back]

     One use of	the GLOB_DOOFFS	flag is	by applications	that build an argument
     list for use with execv, execve or	execvp.	 Suppose, for example, that an
     application wants to do the equivalent of:

	     ls	-l *.c

     But for some reason:

	     system("ls	-l *.c")

     is	not acceptable.	 The application could 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";
	  execp	("ls", &globbuf.gl_pathv[0]);

     Using the same example:

	     ls	-l *.c *.h

     could be approximately simulated using GLOB_APPEND	as follows:

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

APPLICATION USAGE    [Toc]    [Back]

     This function is not provided for the purpose of enabling utilities to
     perform pathname expansion	on their arguments, as the operation is
     performed by the shell, and utilities are explicitly not expected to redo
     this.  Instead, it	is provided for	applications that need to do pathname
     expansion on strings obtained from	other sources, such as a pattern typed
     by	a user or read from a file.

									Page 4

glob(3G)							      glob(3G)

     If	a utility needs	to see if a pathname matches a given pattern, it can
     use fnmatch.

     Note that gl_pathc	and gl_pathv have meaning even if glob fails.  This
     allows glob to report partial results in the event	of an error.  However,
     if	gl_pathc is zero, gl_pathv is unspecified even if glob did not return
     an	error.

     The GLOB_NOCHECK option could be used when	an application wants to	expand
     a pathname	if wildcards are specified, but	wants to treat the pattern as
     just a string otherwise.  The sh utility might use	this for optionarguments,
	for example.

     The new pathnames generated by a subsequent call with GLOB_APPEND are not
     sorted together with the previous pathnames.  This	mirrors	the way	that
     the sheel handles pathname	expansion when multiple	expansions are done on
     a command line.

     Applications that need tilde and parameter	expansion should use wordexp.

SEE ALSO    [Toc]    [Back]

     execv(2), fnmatch(3g), opendir(3b), readdir(3b), stat(2), wordexp(3g),

									PPPPaaaaggggeeee 5555
[ Back ]
 Similar pages
Name OS Title
bzfgrep FreeBSD print lines matching a pattern
grep FreeBSD print lines matching a pattern
zfgrep FreeBSD print lines matching a pattern
egrep FreeBSD print lines matching a pattern
fgrep FreeBSD print lines matching a pattern
bzgrep FreeBSD print lines matching a pattern
zgrep FreeBSD print lines matching a pattern
zegrep FreeBSD print lines matching a pattern
gmatch IRIX shell global pattern matching
bzegrep FreeBSD print lines matching a pattern
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service