ef_list_expansions man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

ef_expand_file(Interactive Command-line Input Library Fuef_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. Otherwise,
       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 charac‐
		ter 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 filename.
       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 argu‐
       ment. 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_ExpandFile().

       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 utility,
       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 speci‐
       fied 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-expansion
       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).\n", arg,
		     ef_last_error(ef));
	      } else {
		 printf("%s matches the following files:\n", arg);
		 for(i=0; i<expn->nfile; i++)
		     printf(" %s\n", 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)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net