.\" Copyright (C) 2000, 2001 by Martin C. Shepherd.\" .\" All rights reserved..\" .\" Permission is hereby granted, free of charge, to any person obtaining a.\" copy of this software and associated documentation files (the.\" "Software"), to deal in the Software without restriction, including.\" without limitation the rights to use, copy, modify, merge, publish,.\" distribute, and/or sell copies of the Software, and to permit persons.\" to whom the Software is furnished to do so, provided that the above.\" copyright notice(s) and this permission notice appear in all copies of.\" the Software and that both the above copyright notice(s) and this.\" permission notice appear in supporting documentation..\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE..\" .\" Except as contained in this notice, the name of a copyright holder.\" shall not be used in advertising or otherwise to promote the sale, use.\" or other dealings in this Software without prior written authorization.\" of the copyright holder..TH ef_expand_file 3.SH NAMEef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions, new_ExpandFile \- expand filenames containing ~user/$envvar and wildcard expressions.SH SYNOPSIS.nf#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);.fi.SH DESCRIPTIONThe \f3ef_expand_file()\f1 function is part of the tecla library(see the libtecla(3) man page). It expands a specified filename,converting \f3~user/\f1 and \f3~/\f1 expressions at the start of thefilename to the corresponding home directories, replacing\f3$envvar\f1 with the value of the corresponding environmentvariable, and then, if there are any wildcards, matching these againstexisting filenames. Backslashes in the input filename are interpretedas escaping any special meanings of the characters that follow them.Only backslahes that are themselves preceded by backslashes arepreserved in the expanded filename..spIn the presence of wildcards, the returned list of filenames onlyincludes the names of existing files which match thewildcards. Otherwise, the original filename is returned afterexpansion of tilde and dollar expressions, and the result is notchecked against existing files. This mimics the file-globbing behaviorof the unix \f3tcsh\f1 shell..spThe supported wildcards and their meanings are:.nf  *        -  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'..fiNote that wildcards never match the initial dot in filenames thatstart with '.'. The initial '.' must be explicitly specified in thefilename. This again mimics the globbing behavior of most unix shells,and its rational is based in the fact that in unix, files with namesthat start with '.' are usually hidden configuration files, which arenot listed by default by the ls command..spThe following is a complete example of how to use the file expansionfunction..nf  #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;  }.fi.spDescriptions of the functions used above are as follows:.sp.nf  ExpandFile *new_ExpandFile(void).fi.spThis function creates the resources used by the \f3ef_expand_file()\f1function. In particular, it maintains the memory that is used to record thearray of matching filenames that is returned by \f3ef_expand_file()\f1. Thisarray is expanded as needed, so there is no built in limit to the number offiles that can be matched..sp.nf  ExpandFile *del_ExpandFile(ExpandFile *ef).fi.spThis function deletes the resources that were returned by a previous call to\f3new_ExpandFile()\f1. It always returns \f3NULL\f1 (ie a deleted object). Itdoes nothing if the \f3ef\f1 argument is \f3NULL\f1..spA container of the following type is returned by \f3ef_expand_file()\f1..sp.nf  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;.fi.sp.nf  FileExpansion *ef_expand_file(ExpandFile *ef,                                const char *path,                                int pathlen).fi.spThe \f3ef_expand_file()\f1 function performs filename expansion, as documentedat the start of this section. Its first argument is a resource object returnedby \f3new_ExpandFile()\f1. A pointer to the start of the filename to be matchedis passed via the \f3path\f1 argument. This must be a normal \f3NUL\f1terminated string, but unless a length of -1 is passed in \f3pathlen\f1, onlythe first \f3pathlen\f1 characters will be used in the filename expansion.  Ifthe length is specified as -1, the whole of the string will beexpanded..spThe function returns a pointer to a container who's contents are theresults of the expansion. If there were no wildcards in the filename,the \f3nfile\f1 member will be 1, and the \f3exists\f1 member shouldbe queried if it is important to know if the expanded file currentlyexists or not. If there were wildcards, then the contained\f3files[]\f1 array will contain the names of the \f3nfile\f1 existingfiles that matched the wildcarded filename, and the \f3exists\f1member will have the value 1. Note that the returned container belongsto the specified \f3ef\f1 object, and its contents will change on eachcall, so if you need to retain the results of more than one call to\f3ef_expand_file()\f1, you should either make a private copy of thereturned results, or create multiple file-expansion resource objectsvia multiple calls to \f3new_ExpandFile()\f1..spOn error, \f3NULL\f1 is returned, and an explanation of the error canbe determined by calling \f3ef_last_error(ef)\f1..sp.nf  const char *ef_last_error(ExpandFile *ef).fi.spThis function returns the message which describes the error thatoccurred on the last call to \f3ef_expand_file()\f1, for the given\f3(ExpandFile *ef)\f1 resource object..sp.nf  int ef_list_expansions(FileExpansion *result, FILE *fp,                         int terminal_width);.fi.spThe \f3ef_list_expansions()\f1 function provides a convenient way tolist the filename expansions returned by \f3ef_expand_file()\f1. Likethe unix \f3ls\f1 command, it arranges the filenames into equal widthcolumns, each column having the width of the largest file. The numberof columns used is thus determined by the length of the longestfilename, and the specified terminal width. Beware that filenames thatare longer than the specified terminal width are printed without beingtruncated, so output longer than the specified terminal width canoccur. The list is written to the stdio stream specified by the\f3fp\f1 argument..SH THREAD SAFETYIn multi-threaded programs, you should use the \f3libtecla_r.a\f1version of the library. This uses POSIX reentrant functions whereavailable (hence the \f3_r\f1 suffix), and disables features that relyon non-reentrant system functions. Currently there are no featuresdisabled in this module.Using the \f3libtecla_r.a\f1 version of the library, it is safe to usethe facilities of this module in multiple threads, provided that eachthread uses a separately allocated \f3ExpandFile\f1 object. In otherwords, if two threads want to do file expansion, they should each call\f3new_ExpandFile()\f1 to allocate their own file-expansion objects..SH FILES.nflibtecla.a    -    The tecla librarylibtecla.h    -    The tecla header file..fi.SH SEE ALSOlibtecla(3), gl_get_line(3), cpl_complete_word(3), pca_lookup_file(3)  .SH AUTHORMartin Shepherd  (mcs@astro.caltech.edu)