1ef_expand_file(3ITnEtCeLrAa)ctive Command-line Input Library Funecft_ieoxnpsand_file(3TECLA)
2
3
4

NAME

6       ef_expand_file,   del_ExpandFile,   ef_last_error,  ef_list_expansions,
7       new_ExpandFile - expand filename and wildcard expressions
8

SYNOPSIS

10       cc [ flag... ] file... -ltecla [ library... ]
11       #include <libtecla.h>
12
13       ExpandFile *ef_expand_file(void);
14
15
16       ExpandFile *del_ExpandFile(ExpandFile *ef);
17
18
19       FileExpansion *ef_last_error(ExpandFile *ef, const char *path,
20            int pathlen);
21
22
23       int ef_list_expansions(FileExpansion *result, FILE *fp, int term_width);
24
25
26       const char *new_ExpandFile(ExpandFile *ef);
27
28

DESCRIPTION

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
40
41       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
47
48       The supported wildcards and their meanings are:
49
50       *           Match any sequence of zero or more characters.
51
52
53       ?           Match any single character.
54
55
56       [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
68
69       [^chars]    The same as [chars] except that it matches any single char‐
70                   acter that does not appear in chars.
71
72
73
74       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
81
82       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
88
89       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
93
94       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
103         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
109
110
111       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
124
125       On error, NULL is returned, and an explanation  of  the  error  can  be
126       determined by calling ef_last_error(ef).
127
128
129       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
133
134       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
144   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

EXAMPLES

152       Example 1 Use of file expansion function.
153
154
155       The  following  is  a complete example of how to use the file expansion
156       function.
157
158
159         #include <stdio.h>
160         #include <libtecla.h>
161
162         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
169             ef = new_ExpandFile();
170             if(!ef)
171                 return 1;
172
173             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
184             ef = del_ExpandFile(ef);
185             return 0;
186         }
187
188

ATTRIBUTES

190       See attributes(5) for descriptions of the following attributes:
191
192
193
194
195       ┌─────────────────────────────┬─────────────────────────────┐
196       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
197       ├─────────────────────────────┼─────────────────────────────┤
198       │Interface Stability          │Evolving                     │
199       ├─────────────────────────────┼─────────────────────────────┤
200       │MT-Level                     │MT-Safe                      │
201       └─────────────────────────────┴─────────────────────────────┘
202

SEE ALSO

204       cpl_complete_word(3TECLA),     gl_get_line(3TECLA),     libtecla(3LIB),
205       pca_lookup_file(3TECLA), attributes(5)
206
207
208
209SunOS 5.11                        1 Jun 2004            ef_expand_file(3TECLA)
Impressum