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 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 follow 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.

?

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 loses 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 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().

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 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 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 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-expansion objects.

Examples

Example 1 Use of file expansion function.

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