ef_expand_file(3TECLA)				 Interactive Command-line Input Library Functions			    ef_expand_file(3TECLA)

NAME

       ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions, new_ExpandFile - expand filename and wildcard expressions

SYNOPSIS

       cc [ flag... ] file... -ltecla [ library... ]
       #include <libtecla.h>

       ExpandFile *ef_expand_file(void);

       ExpandFile *del_ExpandFile(ExpandFile *ef);

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

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

       const char *new_ExpandFile(ExpandFile *ef);

DESCRIPTION

       The  ef_expand_file() function is part of the libtecla(3LIB) library. 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 corresponding environment vari-
       able, 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 backslashes that are themselves preceded	by  backslashes  are  pre-
       served in the expanded filename.

       In  the	presence  of wildcards, the returned list of filenames includes only 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 loses 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 does not 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(1) command.

       The  new_ExpandFile()  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 file names that is returned by ef_expand_file(). This array is expanded as	needed,  so  there  is	no
       builtin limit to the number of files that can be matched.

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

       The ef_expand_file() function performs filename expansion. Its first argument is a resource object returned by new_ExpandFile(). A  pointer
       to  the	start  of  the	filename  to be matched is passed by the path argument. This must be a normal null-terminated string, but unless a
       length of -1 is passed in pathlen, only the first pathlen characters will be used in the filename expansion. If the length is specified	as
       -1, the whole of the string will be expanded. 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;

       The  ef_expand_file() function returns a pointer to a container whose 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  cur-
       rently  exists.	If there were wild cards, 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 with multiple calls  to  new_Expand-
       File().

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

       The  ef_last_error()  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.

       The ef_list_expansions() function provides a convenient way to list the filename expansions returned by ef_expand_file(). Like the ls util-
       ity,  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
       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-expan-
       sion objects.

EXAMPLES

       Example 1: Use of file expansion function.

       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;
       }

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       cpl_complete_word(3TECLA), gl_get_line(3TECLA), libtecla(3LIB), pca_lookup_file(3TECLA), attributes(5)

SunOS 5.10							    1 Jun 2004						    ef_expand_file(3TECLA)