ef_expand_file(3)					     Library Functions Manual						 ef_expand_file(3)

NAME

       ef_expand_file,	del_ExpandFile, ef_last_error, ef_list_expansions, new_ExpandFile - expand filenames containing ~user/$envvar and wildcard
       expressions

SYNOPSIS

       #include <libtecla.h>

       ExpandFile *new_ExpandFile(void);

       ExpandFile *del_ExpandFile(ExpandFile *ef);

       FileExpansion *ef_expand_file(ExpandFile *ef,
				     const char *path,
				     int pathlen);

       int ef_list_expansions(FileExpansion *result, FILE *fp,
			      int term_width);

       const char *ef_last_error(ExpandFile *ef);

DESCRIPTION

       The ef_expand_file() function is part of the tecla library (see the libtecla(3) man page). It  expands  a  specified  filename,	converting
       ~user/  and ~/ expressions at the start of the filename to the corresponding home directories, replacing $envvar with the value of the cor-
       responding environment variable, and then, if there are any wildcards, matching these against existing filenames. Backslashes in the  input
       filename are interpreted as escaping any special meanings of the characters that follow them.  Only backslahes that are themselves preceded
       by backslashes are preserved in the expanded filename.

       In the presence of wildcards, the returned list of filenames only includes the names of existing files which match  the	wildcards.  Other-
       wise,  the  original  filename  is returned after expansion of tilde and dollar expressions, and the result is not checked against existing
       files. This mimics the file-globbing behavior of the unix tcsh shell.

       The supported wildcards and their meanings are:
	 *	  -  Match any sequence of zero or more characters.
	 ?	  -  Match any single character.
	 [chars]  -  Match any single character that appears in
		     'chars'.  If 'chars' contains an expression of
		     the form a-b, then any character between a and
		     b, including a and b, matches. The '-'
		     character looses its special meaning as a
		     range specifier when it appears at the start
		     of the sequence of characters. The ']'
		     character also looses its significance as the
		     terminator of the range expression if it
		     appears immediately after the opening '[', at
		     which point it is treated one of the
		     characters of the range. If you want both '-'
		     and ']' to be part of the range, the '-'
		     should come first and the ']' second.

	 [^chars] -  The same as [chars] except that it matches any
		     single character that doesn't appear in
		     'chars'.

       Note that wildcards never match the initial dot in filenames that start with '.'. The initial '.' must be explicitly specified in the file-
       name.  This  again  mimics  the globbing behavior of most unix shells, and its rational is based in the fact that in unix, files with names
       that start with '.' are usually hidden configuration files, which are not listed by default by the ls command.

       The following is a complete example of how to use the file expansion function.

	 #include <stdio.h>
	 #include <libtecla.h>

	 int main(int argc, char *argv[])
	 {
	   ExpandFile *ef;	/* The expansion resource object */
	   char *filename;	/* The filename being expanded */
	   FileExpansion *expn; /* The results of the expansion */
	   int i;

	   ef = new_ExpandFile();
	   if(!ef)
	     return 1;

	   for(arg = *(argv++); arg; arg = *(argv++)) {
	     if((expn = ef_expand_file(ef, arg, -1)) == NULL) {
	       fprintf(stderr, "Error expanding %s (%s).
", arg,
				ef_last_error(ef));
	     } else {
	       printf("%s matches the following files:
", arg);
	       for(i=0; i<expn->nfile; i++)
		 printf(" %s
", expn->files[i]);
	     }
	   }

	   ef = del_ExpandFile(ef);
	   return 0;
	 }

       Descriptions of the functions used above are as follows:

	 ExpandFile *new_ExpandFile(void)

       This function creates the resources used by the ef_expand_file() function. In particular, it maintains the memory that is  used	to  record
       the  array  of  matching filenames that is returned by ef_expand_file(). This array is expanded as needed, so there is no built in limit to
       the number of files that can be matched.

	 ExpandFile *del_ExpandFile(ExpandFile *ef)

       This function deletes the resources that were returned by a previous call to  new_ExpandFile().	It  always  returns  NULL  (ie	a  deleted
       object). It does nothing if the ef argument is NULL.

       A container of the following type is returned by ef_expand_file().

	 typedef struct {
	   int exists;	 /* True if the files in files[] exist */
	   int nfile;	 /* The number of files in files[] */
	   char **files; /* An array of 'nfile' filenames. */
	 } FileExpansion;

	 FileExpansion *ef_expand_file(ExpandFile *ef,
				       const char *path,
				       int pathlen)

       The  ef_expand_file()  function	performs  filename expansion, as documented at the start of this section. Its first argument is a resource
       object returned by new_ExpandFile(). A pointer to the start of the filename to be matched is passed via the path argument. This must  be  a
       normal  NUL  terminated string, but unless a length of -1 is passed in pathlen, only the first pathlen characters will be used in the file-
       name expansion.	If the length is specified as -1, the whole of the string will be expanded.

       The function returns a pointer to a container who's contents are the results of the expansion. If there were no wildcards in the  filename,
       the  nfile  member  will  be 1, and the exists member should be queried if it is important to know if the expanded file currently exists or
       not. If there were wildcards, then the contained files[] array will contain the names of the nfile existing files that  matched	the  wild-
       carded  filename, and the exists member will have the value 1. Note that the returned container belongs to the specified ef object, and its
       contents will change on each call, so if you need to retain the results of more than one call to ef_expand_file(), you should either make a
       private copy of the returned results, or create multiple file-expansion resource objects via multiple calls to new_ExpandFile().

       On error, NULL is returned, and an explanation of the error can be determined by calling ef_last_error(ef).

	 const char *ef_last_error(ExpandFile *ef)

       This  function  returns the message which describes the error that occurred on the last call to ef_expand_file(), for the given (ExpandFile
       *ef) resource object.

	 int ef_list_expansions(FileExpansion *result, FILE *fp,
				int terminal_width);

       The ef_list_expansions() function provides a convenient way to list the filename expansions returned by ef_expand_file(). Like the unix	ls
       command,  it  arranges the filenames into equal width columns, each column having the width of the largest file. The number of columns used
       is thus determined by the length of the longest filename, and the specified terminal width. Beware that filenames that are longer than  the
       specified  terminal  width  are	printed without being truncated, so output longer than the specified terminal width can occur. The list is
       written to the stdio stream specified by the fp argument.

THREAD SAFETY

       In multi-threaded programs, you should use the libtecla_r.a version of the library. This uses POSIX  reentrant  functions  where  available
       (hence  the _r suffix), and disables features that rely on non-reentrant system functions. Currently there are no features disabled in this
       module.

       Using the libtecla_r.a version of the library, it is safe to use the facilities of this module in  multiple  threads,  provided	that  each
       thread  uses  a	separately  allocated  ExpandFile  object. In other words, if two threads want to do file expansion, they should each call
       new_ExpandFile() to allocate their own file-expansion objects.

FILES

       libtecla.a    -	  The tecla library
       libtecla.h    -	  The tecla header file.

SEE ALSO

       libtecla(3), gl_get_line(3), cpl_complete_word(3),
       pca_lookup_file(3)

AUTHOR

       Martin Shepherd	(mcs@astro.caltech.edu)

																 ef_expand_file(3)