7 .\" to whom the Software is furnished to do so, provided that the above
8 .\" copyright notice(s) and this permission notice appear in all copies of
9 .\" the Software and that both the above copyright notice(s) and this
10 .\" permission notice appear in supporting documentation.
11 .\"
12 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
13 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
14 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
15 .\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
16 .\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
17 .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
18 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
19 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
20 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21 .\"
22 .\" Except as contained in this notice, the name of a copyright holder
23 .\" shall not be used in advertising or otherwise to promote the sale, use
24 .\" or other dealings in this Software without prior written authorization
25 .\" of the copyright holder.
26 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
27 .TH PCA_LOOKUP_FILE 3TECLA "Aug 13, 2007"
28 .SH NAME
29 pca_lookup_file, del_PathCache, del_PcaPathConf, new_PathCache,
30 new_PcaPathConf, pca_last_error, pca_path_completions, pca_scan_path,
31 pca_set_check_fn, ppc_file_start, ppc_literal_escapes \- lookup a file in a
32 list of directories
33 .SH SYNOPSIS
34 .LP
35 .nf
36 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
37 #include <libtecla.h>
38
39 \fBchar *\fR\fBpca_lookup_file\fR(\fBPathCache *\fR\fIpc\fR, \fBconst char *\fR\fIname\fR,
40 \fBint\fR \fIname_len\fR, \fBint\fR \fIliteral\fR);
41 .fi
42
43 .LP
44 .nf
45 \fBPathCache *\fR\fBdel_PathCache\fR(\fBPathCache *\fR\fIpc\fR);
46 .fi
47
48 .LP
49 .nf
50 \fBPcaPathConf *\fR\fBdel_PcaPathConf\fR(\fBPcaPathConf *\fR\fIppc\fR);
51 .fi
52
53 .LP
54 .nf
75 \fBint\fR \fBpca_scan_path\fR(\fBPathCache *\fR\fIpc\fR, \fBconst char *\fR\fIpath\fR);
76 .fi
77
78 .LP
79 .nf
80 \fBvoid\fR \fBpca_set_check_fn\fR(\fBPathCache *\fR\fIpc\fR, \fBCplCheckFn *\fR\fIcheck_fn\fR,
81 \fBvoid *\fR\fIdata\fR);
82 .fi
83
84 .LP
85 .nf
86 \fBvoid\fR \fBppc_file_start\fR(\fBPcaPathConf *\fR\fIppc\fR, \fBint\fR \fIstart_index\fR);
87 .fi
88
89 .LP
90 .nf
91 \fBvoid\fR \fBppc_literal_escapes\fR(\fBPcaPathConf *\fR\fIppc\fR, \fBint\fR \fIliteral\fR);
92 .fi
93
94 .SH DESCRIPTION
95 .sp
96 .LP
97 The \fBPathCache\fR object is part of the \fBlibtecla\fR(3LIB) library.
98 \fBPathCache\fR objects allow an application to search for files in any colon
99 separated list of directories, such as the UNIX execution \fBPATH\fR
100 environment variable. Files in absolute directories are cached in a
101 \fBPathCache\fR object, whereas relative directories are scanned as needed.
102 Using a \fBPathCache\fR object, you can look up the full pathname of a simple
103 filename, or you can obtain a list of the possible completions of a given
104 filename prefix. By default all files in the list of directories are targets
105 for lookup and completion, but a versatile mechanism is provided for only
106 selecting specific types of files. The obvious application of this facility is
107 to provide Tab-completion and lookup of executable commands in the UNIX
108 \fBPATH\fR, so an optional callback which rejects all but executable files, is
109 provided.
110 .SS "An Example"
111 .sp
112 .LP
113 Under UNIX, the following example program looks up and displays the full
114 pathnames of each of the command names on the command line.
115 .sp
116 .in +2
117 .nf
118 #include <stdio.h>
119 #include <stdlib.h>
120 #include <libtecla.h>
121
122 int main(int argc, char *argv[])
123 {
124 int i;
125 /*
126 * Create a cache for executable files.
127 */
128 PathCache *pc = new_PathCache();
129 if(!pc)
130 exit(1);
131 /*
132 * Scan the user's PATH for executables.
152 return 0;
153 }
154 .fi
155 .in -2
156
157 .sp
158 .LP
159 The following is an example of what this does on a laptop under LINUX:
160 .sp
161 .in +2
162 .nf
163 $ ./example less more blob
164 The full pathname of 'less' is /usr/bin/less
165 The full pathname of 'more' is /bin/more
166 The full pathname of 'blob' is unknown
167 $
168 .fi
169 .in -2
170
171 .SS "Function Descriptions"
172 .sp
173 .LP
174 To use the facilities of this module, you must first allocate a \fBPathCache\fR
175 object by calling the \fBnew_PathCache()\fR constructor function. This function
176 creates the resources needed to cache and lookup files in a list of
177 directories. It returns \fINULL\fR on error.
178 .SS "Populating The Cache"
179 .sp
180 .LP
181 Once you have created a cache, it needs to be populated with files. To do this,
182 call the \fBpca_scan_path()\fR function. Whenever this function is called, it
183 discards the current contents of the cache, then scans the list of directories
184 specified in its path argument for files. The path argument must be a string
185 containing a colon-separated list of directories, such as
186 "\fB/usr/bin\fR:\fB/home/mcs/bin\fR:". This can include directories specified
187 by absolute pathnames such as "\fB/usr/bin\fR", as well as sub-directories
188 specified by relative pathnames such as "." or "\fBbin\fR". Files in the
189 absolute directories are immediately cached in the specified \fBPathCache\fR
190 object, whereas subdirectories, whose identities obviously change whenever the
191 current working directory is changed, are marked to be scanned on the fly
192 whenever a file is looked up.
193 .sp
194 .LP
195 On success this function return 0. On error it returns 1, and a description of
196 the error can be obtained by calling \fBpca_last_error\fR(\fIpc\fR).
197 .SS "Looking Up Files"
198 .sp
199 .LP
200 Once the cache has been populated with files, you can look up the full pathname
201 of a file, simply by specifying its filename to \fBpca_lookup_file()\fR.
202 .sp
203 .LP
204 To make it possible to pass this function a filename which is actually part of
205 a longer string, the \fIname_len\fR argument can be used to specify the length
206 of the filename at the start of the \fIname\fR[] argument. If you pass -1 for
207 this length, the length of the string will be determined with \fIstrlen\fR. If
208 the \fIname\fR[] string might contain backslashes that escape the special
209 meanings of spaces and tabs within the filename, give the \fIliteral\fR
210 argument the value 0. Otherwise, if backslashes should be treated as normal
211 characters, pass 1 for the value of the \fIliteral\fR argument.
212 .SS "Filename Completion"
213 .sp
214 .LP
215 Looking up the potential completions of a filename-prefix in the filename cache
216 is achieved by passing the provided \fBpca_path_completions()\fR callback
217 function to the \fBcpl_complete_word\fR(3TECLA) function.
218 .sp
219 .LP
220 This callback requires that its data argument be a pointer to a PcaPathConf
221 object. Configuration objects of this type are allocated by calling
222 \fBnew_PcaPathConf()\fR.
223 .sp
224 .LP
225 This function returns an object initialized with default configuration
226 parameters, which determine how the \fBcpl_path_completions()\fR callback
227 function behaves. The functions which allow you to individually change these
228 parameters are discussed below.
229 .sp
230 .LP
231 By default, the \fBpca_path_completions()\fR callback function searches
232 backwards for the start of the filename being completed, looking for the first
233 un-escaped space or the start of the input line. If you wish to specify a
234 different location, call \fBppc_file_start()\fR with the index at which the
235 filename starts in the input line. Passing \fIstart_index\fR=-1 re-enables the
236 default behavior.
237 .sp
238 .LP
239 By default, when \fBpca_path_completions()\fR looks at a filename in the input
240 line, each lone backslash in the input line is interpreted as being a special
241 character which removes any special significance of the character which follows
242 it, such as a space which should be taken as part of the filename rather than
243 delimiting the start of the filename. These backslashes are thus ignored while
244 looking for completions, and subsequently added before spaces, tabs and literal
245 backslashes in the list of completions. To have unescaped backslashes treated
246 as normal characters, call \fBppc_literal_escapes()\fR with a non-zero value in
247 its literal argument.
248 .sp
249 .LP
250 When you have finished with a \fBPcaPathConf\fR variable, you can pass it to
251 the \fBdel_PcaPathConf()\fR destructor function to reclaim its memory.
252 .SS "Being Selective"
253 .sp
254 .LP
255 If you are only interested in certain types or files, such as, for example,
256 executable files, or files whose names end in a particular suffix, you can
257 arrange for the file completion and lookup functions to be selective in the
258 filenames that they return. This is done by registering a callback function
259 with your \fBPathCache\fR object. Thereafter, whenever a filename is found
260 which either matches a filename being looked up or matches a prefix which is
261 being completed, your callback function will be called with the full pathname
262 of the file, plus any application-specific data that you provide. If the
263 callback returns 1 the filename will be reported as a match. If it returns 0,
264 it will be ignored. Suitable callback functions and their prototypes should be
265 declared with the following macro. The \fBCplCheckFn\fR typedef is also
266 provided in case you wish to declare pointers to such functions
267 .sp
268 .in +2
269 .nf
270 #define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
271 typedef CPL_CHECK_FN(CplCheckFn);
272 .fi
273 .in -2
274
275 .sp
276 .LP
277 Registering one of these functions involves calling the
278 \fBpca_set_check_fn()\fR function. In addition to the callback function passed
279 with the \fIcheck_fn\fR argument, you can pass a pointer to anything with the
280 \fIdata\fR argument. This pointer will be passed on to your callback function
281 by its own \fIdata\fR argument whenever it is called, providing a way to pass
282 application-specific data to your callback. Note that these callbacks are
283 passed the full pathname of each matching file, so the decision about whether a
284 file is of interest can be based on any property of the file, not just its
285 filename. As an example, the provided \fBcpl_check_exe()\fR callback function
286 looks at the executable permissions of the file and the permissions of its
287 parent directories, and only returns 1 if the user has execute permission to
288 the file. This callback function can thus be used to lookup or complete command
289 names found in the directories listed in the user's \fBPATH\fR environment
290 variable. The example program above provides a demonstration of this.
291 .sp
292 .LP
293 Beware that if somebody tries to complete an empty string, your callback will
294 get called once for every file in the cache, which could number in the
295 thousands. If your callback does anything time consuming, this could result in
296 an unacceptable delay for the user, so callbacks should be kept short.
297 .sp
298 .LP
299 To improve performance, whenever one of these callbacks is called, the choice
300 that it makes is cached, and the next time the corresponding file is looked up,
301 instead of calling the callback again, the cached record of whether it was
302 accepted or rejected is used. Thus if somebody tries to complete an empty
303 string, and hits tab a second time when nothing appears to happen, there will
304 only be one long delay, since the second pass will operate entirely from the
305 cached dispositions of the files. These cached dipositions are discarded
306 whenever \fBpca_scan_path()\fR is called, and whenever \fBpca_set_check_fn()\fR
307 is called with changed callback function or \fIdata\fR arguments.
308 .SS "Error Handling"
309 .sp
310 .LP
311 If \fBpca_scan_path()\fR reports that an error occurred by returning 1, you can
312 obtain a terse description of the error by calling
313 \fBpca_last_error\fR(\fIpc\fR). This returns an internal string containing an
314 error message.
315 .SS "Cleaning Up"
316 .sp
317 .LP
318 Once you have finished using a \fBPathCache\fR object, you can reclaim its
319 resources by passing it to the \fBdel_PathCache()\fR destructor function. This
320 takes a pointer to one of these objects, and always returns \fINULL\fR.
321 .SS "Thread Safety"
322 .sp
323 .LP
324 It is safe to use the facilities of this module in multiple threads, provided
325 that each thread uses a separately allocated \fBPathCache\fR object. In other
326 words, if two threads want to do path searching, they should each call
327 \fBnew_PathCache()\fR to allocate their own caches.
328 .SH ATTRIBUTES
329 .sp
330 .LP
331 See \fBattributes\fR(5) for descriptions of the following attributes:
332 .sp
333
334 .sp
335 .TS
336 box;
337 c | c
338 l | l .
339 ATTRIBUTE TYPE ATTRIBUTE VALUE
340 _
341 Interface Stability Evolving
342 _
343 MT-Level MT-Safe
344 .TE
345
346 .SH SEE ALSO
347 .sp
348 .LP
349 \fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA),
350 \fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB), \fBattributes\fR(5)
|
7 .\" to whom the Software is furnished to do so, provided that the above
8 .\" copyright notice(s) and this permission notice appear in all copies of
9 .\" the Software and that both the above copyright notice(s) and this
10 .\" permission notice appear in supporting documentation.
11 .\"
12 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
13 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
14 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
15 .\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
16 .\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
17 .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
18 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
19 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
20 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21 .\"
22 .\" Except as contained in this notice, the name of a copyright holder
23 .\" shall not be used in advertising or otherwise to promote the sale, use
24 .\" or other dealings in this Software without prior written authorization
25 .\" of the copyright holder.
26 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
27 .TH PCA_LOOKUP_FILE 3TECLA "January 18, 2020"
28 .SH NAME
29 pca_lookup_file, del_PathCache, del_PcaPathConf, new_PathCache,
30 new_PcaPathConf, pca_last_error, pca_path_completions, pca_scan_path,
31 pca_set_check_fn, ppc_file_start, ppc_literal_escapes \- lookup a file in a
32 list of directories
33 .SH SYNOPSIS
34 .nf
35 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
36 #include <libtecla.h>
37
38 \fBchar *\fR\fBpca_lookup_file\fR(\fBPathCache *\fR\fIpc\fR, \fBconst char *\fR\fIname\fR,
39 \fBint\fR \fIname_len\fR, \fBint\fR \fIliteral\fR);
40 .fi
41
42 .LP
43 .nf
44 \fBPathCache *\fR\fBdel_PathCache\fR(\fBPathCache *\fR\fIpc\fR);
45 .fi
46
47 .LP
48 .nf
49 \fBPcaPathConf *\fR\fBdel_PcaPathConf\fR(\fBPcaPathConf *\fR\fIppc\fR);
50 .fi
51
52 .LP
53 .nf
74 \fBint\fR \fBpca_scan_path\fR(\fBPathCache *\fR\fIpc\fR, \fBconst char *\fR\fIpath\fR);
75 .fi
76
77 .LP
78 .nf
79 \fBvoid\fR \fBpca_set_check_fn\fR(\fBPathCache *\fR\fIpc\fR, \fBCplCheckFn *\fR\fIcheck_fn\fR,
80 \fBvoid *\fR\fIdata\fR);
81 .fi
82
83 .LP
84 .nf
85 \fBvoid\fR \fBppc_file_start\fR(\fBPcaPathConf *\fR\fIppc\fR, \fBint\fR \fIstart_index\fR);
86 .fi
87
88 .LP
89 .nf
90 \fBvoid\fR \fBppc_literal_escapes\fR(\fBPcaPathConf *\fR\fIppc\fR, \fBint\fR \fIliteral\fR);
91 .fi
92
93 .SH DESCRIPTION
94 The \fBPathCache\fR object is part of the \fBlibtecla\fR(3LIB) library.
95 \fBPathCache\fR objects allow an application to search for files in any colon
96 separated list of directories, such as the UNIX execution \fBPATH\fR
97 environment variable. Files in absolute directories are cached in a
98 \fBPathCache\fR object, whereas relative directories are scanned as needed.
99 Using a \fBPathCache\fR object, you can look up the full pathname of a simple
100 filename, or you can obtain a list of the possible completions of a given
101 filename prefix. By default all files in the list of directories are targets
102 for lookup and completion, but a versatile mechanism is provided for only
103 selecting specific types of files. The obvious application of this facility is
104 to provide Tab-completion and lookup of executable commands in the UNIX
105 \fBPATH\fR, so an optional callback which rejects all but executable files is
106 provided.
107 .SS "An Example"
108 Under UNIX, the following example program looks up and displays the full
109 pathnames of each of the command names on the command line.
110 .sp
111 .in +2
112 .nf
113 #include <stdio.h>
114 #include <stdlib.h>
115 #include <libtecla.h>
116
117 int main(int argc, char *argv[])
118 {
119 int i;
120 /*
121 * Create a cache for executable files.
122 */
123 PathCache *pc = new_PathCache();
124 if(!pc)
125 exit(1);
126 /*
127 * Scan the user's PATH for executables.
147 return 0;
148 }
149 .fi
150 .in -2
151
152 .sp
153 .LP
154 The following is an example of what this does on a laptop under LINUX:
155 .sp
156 .in +2
157 .nf
158 $ ./example less more blob
159 The full pathname of 'less' is /usr/bin/less
160 The full pathname of 'more' is /bin/more
161 The full pathname of 'blob' is unknown
162 $
163 .fi
164 .in -2
165
166 .SS "Function Descriptions"
167 To use the facilities of this module, you must first allocate a \fBPathCache\fR
168 object by calling the \fBnew_PathCache()\fR constructor function. This function
169 creates the resources needed to cache and lookup files in a list of
170 directories. It returns \fINULL\fR on error.
171 .SS "Populating The Cache"
172 Once you have created a cache, it needs to be populated with files. To do this,
173 call the \fBpca_scan_path()\fR function. Whenever this function is called, it
174 discards the current contents of the cache, then scans the list of directories
175 specified in its path argument for files. The path argument must be a string
176 containing a colon-separated list of directories, such as
177 "\fB/usr/bin\fR:\fB/home/mcs/bin\fR:". This can include directories specified
178 by absolute pathnames such as "\fB/usr/bin\fR", as well as sub-directories
179 specified by relative pathnames such as "." or "\fBbin\fR". Files in the
180 absolute directories are immediately cached in the specified \fBPathCache\fR
181 object, whereas subdirectories, whose identities obviously change whenever the
182 current working directory is changed, are marked to be scanned on the fly
183 whenever a file is looked up.
184 .sp
185 .LP
186 On success this function return 0. On error it returns 1, and a description of
187 the error can be obtained by calling \fBpca_last_error\fR(\fIpc\fR).
188 .SS "Looking Up Files"
189 Once the cache has been populated with files, you can look up the full pathname
190 of a file, simply by specifying its filename to \fBpca_lookup_file()\fR.
191 .sp
192 .LP
193 To make it possible to pass this function a filename which is actually part of
194 a longer string, the \fIname_len\fR argument can be used to specify the length
195 of the filename at the start of the \fIname\fR[] argument. If you pass -1 for
196 this length, the length of the string will be determined with \fIstrlen\fR. If
197 the \fIname\fR[] string might contain backslashes that escape the special
198 meanings of spaces and tabs within the filename, give the \fIliteral\fR
199 argument the value 0. Otherwise, if backslashes should be treated as normal
200 characters, pass 1 for the value of the \fIliteral\fR argument.
201 .SS "Filename Completion"
202 Looking up the potential completions of a filename-prefix in the filename cache
203 is achieved by passing the provided \fBpca_path_completions()\fR callback
204 function to the \fBcpl_complete_word\fR(3TECLA) function.
205 .sp
206 .LP
207 This callback requires that its data argument be a pointer to a PcaPathConf
208 object. Configuration objects of this type are allocated by calling
209 \fBnew_PcaPathConf()\fR.
210 .sp
211 .LP
212 This function returns an object initialized with default configuration
213 parameters, which determine how the \fBcpl_path_completions()\fR callback
214 function behaves. The functions which allow you to individually change these
215 parameters are discussed below.
216 .sp
217 .LP
218 By default, the \fBpca_path_completions()\fR callback function searches
219 backwards for the start of the filename being completed, looking for the first
220 un-escaped space or the start of the input line. If you wish to specify a
221 different location, call \fBppc_file_start()\fR with the index at which the
222 filename starts in the input line. Passing \fIstart_index\fR=-1 re-enables the
223 default behavior.
224 .sp
225 .LP
226 By default, when \fBpca_path_completions()\fR looks at a filename in the input
227 line, each lone backslash in the input line is interpreted as being a special
228 character which removes any special significance of the character which follows
229 it, such as a space which should be taken as part of the filename rather than
230 delimiting the start of the filename. These backslashes are thus ignored while
231 looking for completions, and subsequently added before spaces, tabs and literal
232 backslashes in the list of completions. To have unescaped backslashes treated
233 as normal characters, call \fBppc_literal_escapes()\fR with a non-zero value in
234 its literal argument.
235 .sp
236 .LP
237 When you have finished with a \fBPcaPathConf\fR variable, you can pass it to
238 the \fBdel_PcaPathConf()\fR destructor function to reclaim its memory.
239 .SS "Being Selective"
240 If you are only interested in certain types or files, such as, for example,
241 executable files, or files whose names end in a particular suffix, you can
242 arrange for the file completion and lookup functions to be selective in the
243 filenames that they return. This is done by registering a callback function
244 with your \fBPathCache\fR object. Thereafter, whenever a filename is found
245 which either matches a filename being looked up or matches a prefix which is
246 being completed, your callback function will be called with the full pathname
247 of the file, plus any application-specific data that you provide. If the
248 callback returns 1 the filename will be reported as a match. If it returns 0,
249 it will be ignored. Suitable callback functions and their prototypes should be
250 declared with the following macro. The \fBCplCheckFn\fR typedef is also
251 provided in case you wish to declare pointers to such functions.
252 .sp
253 .in +2
254 .nf
255 #define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
256 typedef CPL_CHECK_FN(CplCheckFn);
257 .fi
258 .in -2
259
260 .sp
261 .LP
262 Registering one of these functions involves calling the
263 \fBpca_set_check_fn()\fR function. In addition to the callback function passed
264 with the \fIcheck_fn\fR argument, you can pass a pointer to anything with the
265 \fIdata\fR argument. This pointer will be passed on to your callback function
266 by its own \fIdata\fR argument whenever it is called, providing a way to pass
267 application-specific data to your callback. Note that these callbacks are
268 passed the full pathname of each matching file, so the decision about whether a
269 file is of interest can be based on any property of the file, not just its
270 filename. As an example, the provided \fBcpl_check_exe()\fR callback function
271 looks at the executable permissions of the file and the permissions of its
272 parent directories, and only returns 1 if the user has execute permission to
273 the file. This callback function can thus be used to lookup or complete command
274 names found in the directories listed in the user's \fBPATH\fR environment
275 variable. The example program above provides a demonstration of this.
276 .sp
277 .LP
278 Beware that if somebody tries to complete an empty string, your callback will
279 get called once for every file in the cache, which could number in the
280 thousands. If your callback does anything time consuming, this could result in
281 an unacceptable delay for the user, so callbacks should be kept short.
282 .sp
283 .LP
284 To improve performance, whenever one of these callbacks is called, the choice
285 that it makes is cached, and the next time the corresponding file is looked up,
286 instead of calling the callback again, the cached record of whether it was
287 accepted or rejected is used. Thus if somebody tries to complete an empty
288 string, and hits tab a second time when nothing appears to happen, there will
289 only be one long delay, since the second pass will operate entirely from the
290 cached dispositions of the files. These cached dispositions are discarded
291 whenever \fBpca_scan_path()\fR is called, and whenever \fBpca_set_check_fn()\fR
292 is called with changed callback function or \fIdata\fR arguments.
293 .SS "Error Handling"
294 If \fBpca_scan_path()\fR reports that an error occurred by returning 1, you can
295 obtain a terse description of the error by calling
296 \fBpca_last_error\fR(\fIpc\fR). This returns an internal string containing an
297 error message.
298 .SS "Cleaning Up"
299 Once you have finished using a \fBPathCache\fR object, you can reclaim its
300 resources by passing it to the \fBdel_PathCache()\fR destructor function. This
301 takes a pointer to one of these objects, and always returns \fINULL\fR.
302 .SS "Thread Safety"
303 It is safe to use the facilities of this module in multiple threads, provided
304 that each thread uses a separately allocated \fBPathCache\fR object. In other
305 words, if two threads want to do path searching, they should each call
306 \fBnew_PathCache()\fR to allocate their own caches.
307 .SH ATTRIBUTES
308 See \fBattributes\fR(5) for descriptions of the following attributes:
309 .sp
310
311 .sp
312 .TS
313 box;
314 c | c
315 l | l .
316 ATTRIBUTE TYPE ATTRIBUTE VALUE
317 _
318 Interface Stability Evolving
319 _
320 MT-Level MT-Safe
321 .TE
322
323 .SH SEE ALSO
324 \fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA),
325 \fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB), \fBattributes\fR(5)
|