Interactive Command-line Input Library Functions
efexpandfile(3TECLA)
NAME
efexpandfile, delExpandFile, eflasterror,
eflistexpansions, newExpandFile - expand filename and
wildcard expressions
SYNOPSIS
cc [ flag... ] file... -ltecla [ library... ]
#include
ExpandFile *efexpandfile(void);
ExpandFile *delExpandFile(ExpandFile *ef);
FileExpansion *eflasterror(ExpandFile *ef, const char *path,
int pathlen);
int eflistexpansions(FileExpansion *result, FILE *fp, int termwidth);
const char *newExpandFile(ExpandFile *ef);
DESCRIPTION
The efexpandfile() 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 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 fol-
low them. Only backslashes that are themselves preceded by
backslashes are preserved 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.
SunOS 5.11 Last change: 1 Jun 2004 1
Interactive Command-line Input Library Functions
efexpandfile(3TECLA)
? 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 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 newExpandFile() function creates the resources used by
the efexpandfile() function. In particular, it maintains
the memory that is used to record the array of matching file
names that is returned by efexpandfile(). This array is
expanded as needed, so there is no builtin limit to the
number of files that can be matched.
The delExpandFile() function deletes the resources that
were returned by a previous call to newExpandFile(). It
always returns NUL (that is, a deleted object). It does
nothing if the ef argument is NUL.
The efexpandfile() function performs filename expansion.
Its first argument is a resource object returned by
newExpandFile(). 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
SunOS 5.11 Last change: 1 Jun 2004 2
Interactive Command-line Input Library Functions
efexpandfile(3TECLA)
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 efexpandfile().
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 efexpandfile() function returns a pointer to a con-
tainer 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 currently 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 efexpandfile(), you should either make a private
copy of the returned results, or create multiple file-
expansion resource objects with multiple calls to
newExpandFile().
On error, NUL is returned, and an explanation of the error
can be determined by calling eflasterror(ef).
The eflasterror() function returns the message which
describes the error that occurred on the last call to
efexpandfile(), for the given (ExpandFile *ef) resource
object.
The eflistexpansions() function provides a convenient way
to list the filename expansions returned by
efexpandfile(). 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 specified terminal width are printed without
being truncated, so output longer than the specified termi-
nal width can occur. The list is written to the stdio stream
specified by the fp argument.
SunOS 5.11 Last change: 1 Jun 2004 3
Interactive Command-line Input Library Functions
efexpandfile(3TECLA)
Thread Safety
It is safe to use the facilities of this module in multiple
threads, provided that each thread uses a separately allo-
cated ExpandFile object. In other words, if two threads want
to do file expansion, they should each call newExpandFile()
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
#include
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 = newExpandFile();
if(!ef)
return 1;
for(arg = *(argv]); arg; arg = *(argv])) {
if((expn = efexpandfile(ef, arg, -1)) == NUL) {
fprintf(stderr, "Error expanding %s (%s).\n", arg,
eflasterror(ef));
} else {
printf("%s matches the following files:\n", arg);
for(i=0; infile; i])
printf(" %s\n", expn->files[i]);
}
}
ef = delExpandFile(ef);
return 0;
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 1 Jun 2004 4
Interactive Command-line Input Library Functions
efexpandfile(3TECLA)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
MT-Level MT-Safe
SEE ALSO
cplcompleteword(3TECLA), glgetline(3TECLA),
libtecla(3LIB), pcalookupfile(3TECLA), attributes(5)
SunOS 5.11 Last change: 1 Jun 2004 5
Interactive Command-line Input Library Functions
efexpandfile(3TECLA)
SunOS 5.11 Last change: 1 Jun 2004 6
|
