ef_expand_file man page on SmartOS

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


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

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

       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.

		   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 '-'	 char‐
		   acter  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 termina‐
		   tor 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 ']'

		   The same as [chars] except that it matches any single char‐
		   acter 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  fol‐
       lowing 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

       Example 1 Use of file expansion function.

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

	 #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();
		 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,
		} 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;

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

       │Interface Stability │ Evolving	      │
       │MT-Level	    │ MT-Safe	      │

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

				  Jun 1, 2004		EF_EXPAND_FILE(3TECLA)

List of man pages available for SmartOS

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]
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