1pca_lookup_file(I3nTtEeCrLaAc)tive Command-line Input Library Fupnccat_iloonoskup_file(3TECLA)
2
6 pca_lookup_file, del_PathCache, del_PcaPathConf, new_PathCache,
7 new_PcaPathConf, pca_last_error, pca_path_completions, pca_scan_path,
8 pca_set_check_fn, ppc_file_start, ppc_literal_escapes - lookup a file
9 in a list of directories
10
12 cc [ flag... ] file... -ltecla [ library... ]
13 #include <libtecla.h>
14 char *pca_lookup_file(PathCache *pc, const char *name,
16 int name_len, int literal);
17 PathCache *del_PathCache(PathCache *pc);
20 PcaPathConf *del_PcaPathConf(PcaPathConf *ppc);
23 PathCache *new_PathCache(void);
26 PcaPathConf *new_PcaPathConf(PathCache *pc);
29 const char *pca_last_error(PathCache *pc);
32 CPL_MATCH_FN(pca_path_completions);
35 int pca_scan_path(PathCache *pc, const char *path);
38 void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn,
41 void *data);
42 void ppc_file_start(PcaPathConf *ppc, int start_index);
45 void ppc_literal_escapes(PcaPathConf *ppc, int literal);
48
51 The PathCache object is part of the libtecla(3LIB) library. PathCache
52 objects allow an application to search for files in any colon separated
53 list of directories, such as the UNIX execution PATH environment vari‐
54 able. Files in absolute directories are cached in a PathCache object,
55 whereas relative directories are scanned as needed. Using a PathCache
56 object, you can look up the full pathname of a simple filename, or you
57 can obtain a list of the possible completions of a given filename pre‐
58 fix. By default all files in the list of directories are targets for
59 lookup and completion, but a versatile mechanism is provided for only
60 selecting specific types of files. The obvious application of this
61 facility is to provide Tab-completion and lookup of executable commands
62 in the UNIX PATH, so an optional callback which rejects all but exe‐
63 cutable files, is provided.
64 An Example
66 Under UNIX, the following example program looks up and displays the
67 full pathnames of each of the command names on the command line.
68 #include <stdio.h>
70 #include <stdlib.h>
71 #include <libtecla.h>
72 int main(int argc, char *argv[])
74 {
75 int i;
76 /*
77 * Create a cache for executable files.
78 */
79 PathCache *pc = new_PathCache();
80 if(!pc)
81 exit(1);
82 /*
83 * Scan the user's PATH for executables.
84 */
85 if(pca_scan_path(pc, getenv("PATH"))) {
86 fprintf(stderr, "%s\n", pca_last_error(pc));
87 exit(1);
88 }
89 /*
90 * Arrange to only report executable files.
91 */
92 pca_set_check_fn(pc, cpl_check_exe, NULL);
93 /*
94 * Lookup and display the full pathname of each of the
95 * commands listed on the command line.
96 */
97 for(i=1; i<argc; i++) {
98 char *cmd = pca_lookup_file(pc, argv[i], -1, 0);
99 printf("The full pathname of '%s' is %s\\n", argv[i],
100 cmd ? cmd : "unknown");
101 }
102 pc = del_PathCache(pc); /* Clean up */
103 return 0;
104 }
105 The following is an example of what this does on a laptop under LINUX:
109 $ ./example less more blob
111 The full pathname of 'less' is /usr/bin/less
112 The full pathname of 'more' is /bin/more
113 The full pathname of 'blob' is unknown
114 $
115 Function Descriptions
118 To use the facilities of this module, you must first allocate a Path‐
119 Cache object by calling the new_PathCache() constructor function. This
120 function creates the resources needed to cache and lookup files in a
121 list of directories. It returns NULL on error.
122 Populating The Cache
124 Once you have created a cache, it needs to be populated with files. To
125 do this, call the pca_scan_path() function. Whenever this function is
126 called, it discards the current contents of the cache, then scans the
127 list of directories specified in its path argument for files. The path
128 argument must be a string containing a colon-separated list of directo‐
129 ries, such as "/usr/bin:/home/mcs/bin:". This can include directories
130 specified by absolute pathnames such as "/usr/bin", as well as sub-
131 directories specified by relative pathnames such as "." or "bin". Files
132 in the absolute directories are immediately cached in the specified
133 PathCache object, whereas subdirectories, whose identities obviously
134 change whenever the current working directory is changed, are marked to
135 be scanned on the fly whenever a file is looked up.
136 On success this function return 0. On error it returns 1, and a
139 description of the error can be obtained by calling pca_last_error(pc).
140 Looking Up Files
142 Once the cache has been populated with files, you can look up the full
143 pathname of a file, simply by specifying its filename to
144 pca_lookup_file().
145 To make it possible to pass this function a filename which is actually
148 part of a longer string, the name_len argument can be used to specify
149 the length of the filename at the start of the name[] argument. If you
150 pass -1 for this length, the length of the string will be determined
151 with strlen. If the name[] string might contain backslashes that escape
152 the special meanings of spaces and tabs within the filename, give the
153 literal argument the value 0. Otherwise, if backslashes should be
154 treated as normal characters, pass 1 for the value of the literal argu‐
155 ment.
156 Filename Completion
158 Looking up the potential completions of a filename-prefix in the file‐
159 name cache is achieved by passing the provided pca_path_completions()
160 callback function to the cpl_complete_word(3TECLA) function.
161 This callback requires that its data argument be a pointer to a PcaP‐
164 athConf object. Configuration objects of this type are allocated by
165 calling new_PcaPathConf().
166 This function returns an object initialized with default configuration
169 parameters, which determine how the cpl_path_completions() callback
170 function behaves. The functions which allow you to individually change
171 these parameters are discussed below.
172 By default, the pca_path_completions() callback function searches back‐
175 wards for the start of the filename being completed, looking for the
176 first un-escaped space or the start of the input line. If you wish to
177 specify a different location, call ppc_file_start() with the index at
178 which the filename starts in the input line. Passing start_index=-1 re-
179 enables the default behavior.
180 By default, when pca_path_completions() looks at a filename in the
183 input line, each lone backslash in the input line is interpreted as
184 being a special character which removes any special significance of the
185 character which follows it, such as a space which should be taken as
186 part of the filename rather than delimiting the start of the filename.
187 These backslashes are thus ignored while looking for completions, and
188 subsequently added before spaces, tabs and literal backslashes in the
189 list of completions. To have unescaped backslashes treated as normal
190 characters, call ppc_literal_escapes() with a non-zero value in its
191 literal argument.
192 When you have finished with a PcaPathConf variable, you can pass it to
195 the del_PcaPathConf() destructor function to reclaim its memory.
196 Being Selective
198 If you are only interested in certain types or files, such as, for
199 example, executable files, or files whose names end in a particular
200 suffix, you can arrange for the file completion and lookup functions to
201 be selective in the filenames that they return. This is done by regis‐
202 tering a callback function with your PathCache object. Thereafter,
203 whenever a filename is found which either matches a filename being
204 looked up or matches a prefix which is being completed, your callback
205 function will be called with the full pathname of the file, plus any
206 application-specific data that you provide. If the callback returns 1
207 the filename will be reported as a match. If it returns 0, it will be
208 ignored. Suitable callback functions and their prototypes should be
209 declared with the following macro. The CplCheckFn typedef is also pro‐
210 vided in case you wish to declare pointers to such functions
211 #define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
213 typedef CPL_CHECK_FN(CplCheckFn);
214 Registering one of these functions involves calling the
218 pca_set_check_fn() function. In addition to the callback function
219 passed with the check_fn argument, you can pass a pointer to anything
220 with the data argument. This pointer will be passed on to your callback
221 function by its own data argument whenever it is called, providing a
222 way to pass application-specific data to your callback. Note that these
223 callbacks are passed the full pathname of each matching file, so the
224 decision about whether a file is of interest can be based on any prop‐
225 erty of the file, not just its filename. As an example, the provided
226 cpl_check_exe() callback function looks at the executable permissions
227 of the file and the permissions of its parent directories, and only
228 returns 1 if the user has execute permission to the file. This callback
229 function can thus be used to lookup or complete command names found in
230 the directories listed in the user's PATH environment variable. The
231 example program above provides a demonstration of this.
232 Beware that if somebody tries to complete an empty string, your call‐
235 back will get called once for every file in the cache, which could num‐
236 ber in the thousands. If your callback does anything time consuming,
237 this could result in an unacceptable delay for the user, so callbacks
238 should be kept short.
239 To improve performance, whenever one of these callbacks is called, the
242 choice that it makes is cached, and the next time the corresponding
243 file is looked up, instead of calling the callback again, the cached
244 record of whether it was accepted or rejected is used. Thus if somebody
245 tries to complete an empty string, and hits tab a second time when
246 nothing appears to happen, there will only be one long delay, since the
247 second pass will operate entirely from the cached dispositions of the
248 files. These cached dipositions are discarded whenever pca_scan_path()
249 is called, and whenever pca_set_check_fn() is called with changed call‐
250 back function or data arguments.
251 Error Handling
253 If pca_scan_path() reports that an error occurred by returning 1, you
254 can obtain a terse description of the error by calling
255 pca_last_error(pc). This returns an internal string containing an error
256 message.
257 Cleaning Up
259 Once you have finished using a PathCache object, you can reclaim its
260 resources by passing it to the del_PathCache() destructor function.
261 This takes a pointer to one of these objects, and always returns NULL.
262 Thread Safety
264 It is safe to use the facilities of this module in multiple threads,
265 provided that each thread uses a separately allocated PathCache object.
266 In other words, if two threads want to do path searching, they should
267 each call new_PathCache() to allocate their own caches.
268
270 See attributes(5) for descriptions of the following attributes:
271 ┌─────────────────────────────┬─────────────────────────────┐
276 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
277 ├─────────────────────────────┼─────────────────────────────┤
278 │Interface Stability │Evolving │
279 ├─────────────────────────────┼─────────────────────────────┤
280 │MT-Level │MT-Safe │
281 └─────────────────────────────┴─────────────────────────────┘
282
284 cpl_complete_word(3TECLA), ef_expand_file(3TECLA), gl_get_line(3TECLA),
285 libtecla(3LIB), attributes(5)
286SunOS 5.11 13 Aug 2007 pca_lookup_file(3TECLA)