2
<title>Manual Page</title>
6
<a href="ef_expand_file.html"><b>ef_expand_file</b></a> <a href="ef_expand_file.html"><b>ef_expand_file</b></a>
10
</pre><h2>NAME</h2><pre>
11
ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions,
12
new_ExpandFile - expand filenames containing ~user/$envvar and wildcard
15
</pre><h2>SYNOPSIS</h2><pre>
16
#include <libtecla.h>
18
ExpandFile *new_ExpandFile(void);
20
ExpandFile *del_ExpandFile(ExpandFile *ef);
22
FileExpansion *ef_expand_file(ExpandFile *ef,
26
int ef_list_expansions(FileExpansion *result, FILE *fp,
29
const char *ef_last_error(ExpandFile *ef);
32
</pre><h2>DESCRIPTION</h2><pre>
33
The ef_expand_file() function is part of the tecla library (see the
34
<a href="libtecla.html"><b>libtecla</b></a> man page). It expands a specified filename,
35
converting ~user/ and ~/ expressions at the start of the filename to
36
the corresponding home directories, replacing $envvar with the value of
37
the corresponding environment variable, and then, if there are any
38
wildcards, matching these against existing filenames. Backslashes in
39
the input filename are interpreted as escaping any special meanings of
40
the characters that follow them. Only backslahes that are themselves
41
preceded by backslashes are preserved in the expanded filename.
43
In the presence of wildcards, the returned list of filenames only
44
includes the names of existing files which match the wildcards. Other-
45
wise, the original filename is returned after expansion of tilde and
46
dollar expressions, and the result is not checked against existing
47
files. This mimics the file-globbing behavior of the unix tcsh shell.
49
The supported wildcards and their meanings are:
50
* - Match any sequence of zero or more characters.
51
? - Match any single character.
52
[chars] - Match any single character that appears in
53
'chars'. If 'chars' contains an expression of
54
the form a-b, then any character between a and
55
b, including a and b, matches. The '-'
56
character looses its special meaning as a
57
range specifier when it appears at the start
58
of the sequence of characters. The ']'
59
character also looses its significance as the
60
terminator of the range expression if it
61
appears immediately after the opening '[', at
62
which point it is treated one of the
63
characters of the range. If you want both '-'
64
and ']' to be part of the range, the '-'
65
should come first and the ']' second.
67
[^chars] - The same as [chars] except that it matches any
68
single character that doesn't appear in
71
Note that wildcards never match the initial dot in filenames that start
72
with '.'. The initial '.' must be explicitly specified in the filename.
73
This again mimics the globbing behavior of most unix shells, and its
74
rational is based in the fact that in unix, files with names that start
75
with '.' are usually hidden configuration files, which are not listed
76
by default by the ls command.
78
The following is a complete example of how to use the file expansion
81
#include <stdio.h>
82
#include <libtecla.h>
84
int main(int argc, char *argv[])
86
ExpandFile *ef; /* The expansion resource object */
87
char *filename; /* The filename being expanded */
88
FileExpansion *expn; /* The results of the expansion */
91
ef = new_ExpandFile();
95
for(arg = *(argv++); arg; arg = *(argv++)) {
96
if((expn = ef_expand_file(ef, arg, -1)) == NULL) {
97
fprintf(stderr, "Error expanding %s (%s).\n", arg,
100
printf("%s matches the following files:\n", arg);
101
for(i=0; i<expn->nfile; i++)
102
printf(" %s\n", expn->files[i]);
106
ef = del_ExpandFile(ef);
110
Descriptions of the functions used above are as follows:
112
ExpandFile *new_ExpandFile(void)
114
This function creates the resources used by the ef_expand_file() func-
115
tion. In particular, it maintains the memory that is used to record the
116
array of matching filenames that is returned by ef_expand_file(). This
117
array is expanded as needed, so there is no built in limit to the num-
118
ber of files that can be matched.
120
ExpandFile *del_ExpandFile(ExpandFile *ef)
122
This function deletes the resources that were returned by a previous
123
call to new_ExpandFile(). It always returns NULL (ie a deleted object).
124
It does nothing if the ef argument is NULL.
126
A container of the following type is returned by ef_expand_file().
129
int exists; /* True if the files in files[] exist */
130
int nfile; /* The number of files in files[] */
131
char **files; /* An array of 'nfile' filenames. */
134
FileExpansion *ef_expand_file(ExpandFile *ef,
138
The ef_expand_file() function performs filename expansion, as docu-
139
mented at the start of this section. Its first argument is a resource
140
object returned by new_ExpandFile(). A pointer to the start of the
141
filename to be matched is passed via the path argument. This must be a
142
normal NUL terminated string, but unless a length of -1 is passed in
143
pathlen, only the first pathlen characters will be used in the filename
144
expansion. If the length is specified as -1, the whole of the string
147
The function returns a pointer to a container who's contents are the
148
results of the expansion. If there were no wildcards in the filename,
149
the nfile member will be 1, and the exists member should be queried if
150
it is important to know if the expanded file currently exists or not.
151
If there were wildcards, then the contained files[] array will contain
152
the names of the nfile existing files that matched the wildcarded file-
153
name, and the exists member will have the value 1. Note that the
154
returned container belongs to the specified ef object, and its contents
155
will change on each call, so if you need to retain the results of more
156
than one call to ef_expand_file(), you should either make a private
157
copy of the returned results, or create multiple file-expansion
158
resource objects via multiple calls to new_ExpandFile().
160
On error, NULL is returned, and an explanation of the error can be
161
determined by calling ef_last_error(ef).
163
const char *ef_last_error(ExpandFile *ef)
165
This function returns the message which describes the error that
166
occurred on the last call to ef_expand_file(), for the given (Expand-
167
File *ef) resource object.
169
int ef_list_expansions(FileExpansion *result, FILE *fp,
172
The ef_list_expansions() function provides a convenient way to list the
173
filename expansions returned by ef_expand_file(). Like the unix ls com-
174
mand, it arranges the filenames into equal width columns, each column
175
having the width of the largest file. The number of columns used is
176
thus determined by the length of the longest filename, and the speci-
177
fied terminal width. Beware that filenames that are longer than the
178
specified terminal width are printed without being truncated, so output
179
longer than the specified terminal width can occur. The list is written
180
to the stdio stream specified by the fp argument.
183
</pre><h2>THREAD SAFETY</h2><pre>
184
In multi-threaded programs, you should use the libtecla_r.a version of
185
the library. This uses POSIX reentrant functions where available (hence
186
the _r suffix), and disables features that rely on non-reentrant system
187
functions. Currently there are no features disabled in this module.
189
Using the libtecla_r.a version of the library, it is safe to use the
190
facilities of this module in multiple threads, provided that each
191
thread uses a separately allocated ExpandFile object. In other words,
192
if two threads want to do file expansion, they should each call
193
new_ExpandFile() to allocate their own file-expansion objects.
196
</pre><h2>FILES</h2><pre>
197
libtecla.a - The tecla library
198
libtecla.h - The tecla header file.
201
</pre><h2>SEE ALSO</h2><pre>
202
<a href="libtecla.html"><b>libtecla</b></a>, <a href="gl_get_line.html"><b>gl_get_line</b></a>, <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>,
203
<a href="pca_lookup_file.html"><b>pca_lookup_file</b></a>
206
</pre><h2>AUTHOR</h2><pre>
207
Martin Shepherd (mcs@astro.caltech.edu)
211
<a href="ef_expand_file.html"><b>ef_expand_file</b></a>
added
removed
src/external/libtecla-1.6.1/html/ef_expand_file.html
