1ef_expand_file(3ITnEtCeLrAa)ctive Command-line Input Library Funecft_ieoxnpsand_file(3TECLA)
2
6 ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions,
7 new_ExpandFile - expand filename and wildcard expressions
8
10 cc [ flag... ] file... -ltecla [ library... ]
11 #include <libtecla.h>
12 ExpandFile *ef_expand_file(void);
14 ExpandFile *del_ExpandFile(ExpandFile *ef);
17 FileExpansion *ef_last_error(ExpandFile *ef, const char *path,
20 int pathlen);
21 int ef_list_expansions(FileExpansion *result, FILE *fp, int term_width);
24 const char *new_ExpandFile(ExpandFile *ef);
27
30 The ef_expand_file() function is part of the libtecla(3LIB) library. It
31 expands a specified filename, converting ~user/ and ~/ expressions at
32 the start of the filename to the corresponding home directories,
33 replacing $envvar with the value of the corresponding environment vari‐
34 able, and then, if there are any wildcards, matching these against
35 existing filenames. Backslashes in the input filename are interpreted
36 as escaping any special meanings of the characters that follow them.
37 Only backslashes that are themselves preceded by backslashes are pre‐
38 served in the expanded filename.
39 In the presence of wildcards, the returned list of filenames includes
42 only the names of existing files which match the wildcards. Otherwise,
43 the original filename is returned after expansion of tilde and dollar
44 expressions, and the result is not checked against existing files. This
45 mimics the file-globbing behavior of the UNIX tcsh shell.
46 The supported wildcards and their meanings are:
49 * Match any sequence of zero or more characters.
51 ? Match any single character.
54 [chars] Match any single character that appears in chars. If chars
57 contains an expression of the form a-b, then any character
58 between a and b, including a and b, matches. The '-' char‐
59 acter loses its special meaning as a range specifier when
60 it appears at the start of the sequence of characters. The
61 ']' character also looses its significance as the termina‐
62 tor of the range expression if it appears immediately after
63 the opening '[', at which point it is treated one of the
64 characters of the range. If you want both '-' and ']' to be
65 part of the range, the '-' should come first and the ']'
66 second.
67 [^chars] The same as [chars] except that it matches any single char‐
70 acter that does not appear in chars.
71 Note that wildcards never match the initial dot in filenames that start
75 with '.'. The initial '.' must be explicitly specified in the filename.
76 This again mimics the globbing behavior of most UNIX shells, and its
77 rational is based in the fact that in UNIX, files with names that start
78 with '.' are usually hidden configuration files, which are not listed
79 by default by the ls(1) command.
80 The new_ExpandFile() function creates the resources used by the
83 ef_expand_file() function. In particular, it maintains the memory that
84 is used to record the array of matching file names that is returned by
85 ef_expand_file(). This array is expanded as needed, so there is no
86 builtin limit to the number of files that can be matched.
87 The del_ExpandFile() function deletes the resources that were returned
90 by a previous call to new_ExpandFile(). It always returns NULL (that
91 is, a deleted object). It does nothing if the ef argument is NULL.
92 The ef_expand_file() function performs filename expansion. Its first
95 argument is a resource object returned by new_ExpandFile(). A pointer
96 to the start of the filename to be matched is passed by the path argu‐
97 ment. This must be a normal null-terminated string, but unless a length
98 of -1 is passed in pathlen, only the first pathlen characters will be
99 used in the filename expansion. If the length is specified as -1, the
100 whole of the string will be expanded. A container of the following type
101 is returned by ef_expand_file().
102 typedef struct {
104 int exists; /* True if the files in files[] exist */
105 int nfile; /* The number of files in files[] */
106 char **files; /* An array of 'nfile' filenames. */
107 } FileExpansion;
108 The ef_expand_file() function returns a pointer to a container whose
112 contents are the results of the expansion. If there were no wildcards
113 in the filename, the nfile member will be 1, and the exists member
114 should be queried if it is important to know if the expanded file cur‐
115 rently exists. If there were wild cards, then the contained files[]
116 array will contain the names of the nfile existing files that matched
117 the wild-carded filename, and the exists member will have the value 1.
118 Note that the returned container belongs to the specified ef object,
119 and its contents will change on each call, so if you need to retain the
120 results of more than one call to ef_expand_file(), you should either
121 make a private copy of the returned results, or create multiple file-
122 expansion resource objects with multiple calls to new_ExpandFile().
123 On error, NULL is returned, and an explanation of the error can be
126 determined by calling ef_last_error(ef).
127 The ef_last_error() function returns the message which describes the
130 error that occurred on the last call to ef_expand_file(), for the given
131 (ExpandFile *ef) resource object.
132 The ef_list_expansions() function provides a convenient way to list the
135 filename expansions returned by ef_expand_file(). Like the ls utility,
136 it arranges the filenames into equal width columns, each column having
137 the width of the largest file. The number of columns used is thus
138 determined by the length of the longest filename, and the specified
139 terminal width. Beware that filenames that are longer than the speci‐
140 fied terminal width are printed without being truncated, so output
141 longer than the specified terminal width can occur. The list is written
142 to the stdio stream specified by the fp argument.
143 Thread Safety
145 It is safe to use the facilities of this module in multiple threads,
146 provided that each thread uses a separately allocated ExpandFile
147 object. In other words, if two threads want to do file expansion, they
148 should each call new_ExpandFile() to allocate their own file-expansion
149 objects.
150
152 Example 1 Use of file expansion function.
153 The following is a complete example of how to use the file expansion
156 function.
157 #include <stdio.h>
160 #include <libtecla.h>
161 int main(int argc, char *argv[])
163 {
164 ExpandFile *ef; /* The expansion resource object */
165 char *filename; /* The filename being expanded */
166 FileExpansion *expn; /* The results of the expansion */
167 int i;
168 ef = new_ExpandFile();
170 if(!ef)
171 return 1;
172 for(arg = *(argv++); arg; arg = *(argv++)) {
174 if((expn = ef_expand_file(ef, arg, -1)) == NULL) {
175 fprintf(stderr, "Error expanding %s (%s).\n", arg,
176 ef_last_error(ef));
177 } else {
178 printf("%s matches the following files:\n", arg);
179 for(i=0; i<expn->nfile; i++)
180 printf(" %s\n", expn->files[i]);
181 }
182 }
183 ef = del_ExpandFile(ef);
185 return 0;
186 }
187
190 See attributes(5) for descriptions of the following attributes:
191 ┌─────────────────────────────┬─────────────────────────────┐
196 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
197 ├─────────────────────────────┼─────────────────────────────┤
198 │Interface Stability │Evolving │
199 ├─────────────────────────────┼─────────────────────────────┤
200 │MT-Level │MT-Safe │
201 └─────────────────────────────┴─────────────────────────────┘
202
204 cpl_complete_word(3TECLA), gl_get_line(3TECLA), libtecla(3LIB),
205 pca_lookup_file(3TECLA), attributes(5)
206SunOS 5.11 1 Jun 2004 ef_expand_file(3TECLA)