1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
|
<head>
<title>Manual Page</title>
</head>
<body>
<pre>
</pre><h2>NAME</h2><pre>
ef_expand_file, del_ExpandFile, ef_last_error,
ef_list_expansions, new_ExpandFile - expand filenames con-
taining ~user/$envvar and wildcard expressions
</pre><h2>SYNOPSIS</h2><pre>
#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);
</pre><h2>DESCRIPTION</h2><pre>
The ef_expand_file() function is part of the tecla library
(see the <a href="libtecla.html">libtecla(3)</a> man page). 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
backslahes that are themselves preceded by backslashes are
preserved in the expanded filename.
In the presence of wildcards, the returned list of filenames
only includes 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 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'.
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 command.
The following is a complete example of how to use the file
expansion function.
#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;
}
Descriptions of the functions used above are as follows:
ExpandFile *new_ExpandFile(void)
This 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
filenames that is returned by ef_expand_file(). This array
is expanded as needed, so there is no built in limit to the
number of files that can be matched.
ExpandFile *del_ExpandFile(ExpandFile *ef)
This function deletes the resources that were returned by a
previous call to new_ExpandFile(). It always returns NULL
(ie a deleted object). It does nothing if the ef argument is
NULL.
A container of the following 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;
FileExpansion *ef_expand_file(ExpandFile *ef,
const char *path,
int pathlen)
The ef_expand_file() function performs filename expansion,
as documented at the start of this section. Its first argu-
ment is a resource object returned by new_ExpandFile(). A
pointer to the start of the filename to be matched is passed
via the path argument. This must be a normal NUL 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.
The function returns a pointer to a container who's 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 or not. 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 via 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).
const char *ef_last_error(ExpandFile *ef)
This 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.
int ef_list_expansions(FileExpansion *result, FILE *fp,
int terminal_width);
The ef_list_expansions() function provides a convenient way
to list the filename expansions returned by
ef_expand_file(). Like the unix ls command, 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.
</pre><h2>THREAD SAFETY</h2><pre>
In multi-threaded programs, you should use the libtecla_r.a
version of the library. This uses POSIX reentrant functions
where available (hence the _r suffix), and disables features
that rely on non-reentrant system functions. Currently there
are no features disabled in this module.
Using the libtecla_r.a version of the library, it is safe to
use the facilities of this module in multiple threads, pro-
vided that each thread uses a separately allocated Expand-
File object. In other words, if two threads want to do file
expansion, they should each call new_ExpandFile() to allo-
cate their own file-expansion objects.
</pre><h2>FILES</h2><pre>
libtecla.a - The tecla library
libtecla.h - The tecla header file.
</pre><h2>SEE ALSO</h2><pre>
<a href="libtecla.html">libtecla(3)</a>, <a href="gl_get_line.html">gl_get_line(3)</a>, <a href="cpl_complete_word.html">cpl_complete_word(3)</a>,
<a href="pca_lookup_file.html">pca_lookup_file(3)</a>
</pre><h2>AUTHOR</h2><pre>
Martin Shepherd (mcs@astro.caltech.edu)
</pre>
</body>
|
