1pca_lookup_file(I3nTtEeCrLaAc)tive Command-line Input Library Fupnccat_iloonoskup_file(3TECLA)
2
3
4

NAME

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

SYNOPSIS

12       cc [ flag... ] file... -ltecla [ library... ]
13       #include <libtecla.h>
14
15       char *pca_lookup_file(PathCache *pc, const char *name,
16            int name_len, int literal);
17
18
19       PathCache *del_PathCache(PathCache *pc);
20
21
22       PcaPathConf *del_PcaPathConf(PcaPathConf *ppc);
23
24
25       PathCache *new_PathCache(void);
26
27
28       PcaPathConf *new_PcaPathConf(PathCache *pc);
29
30
31       const char *pca_last_error(PathCache *pc);
32
33
34       CPL_MATCH_FN(pca_path_completions);
35
36
37       int pca_scan_path(PathCache *pc, const char *path);
38
39
40       void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn,
41            void *data);
42
43
44       void ppc_file_start(PcaPathConf *ppc, int start_index);
45
46
47       void ppc_literal_escapes(PcaPathConf *ppc, int literal);
48
49

DESCRIPTION

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
65   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
69         #include <stdio.h>
70         #include <stdlib.h>
71         #include <libtecla.h>
72
73         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
106
107
108       The following is an example of what this does on a laptop under LINUX:
109
110         $ ./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
116
117   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
123   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
137
138       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
141   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
146
147       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
157   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
162
163       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
167
168       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
173
174       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
181
182       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
193
194       When  you have finished with a PcaPathConf variable, you can pass it to
195       the del_PcaPathConf() destructor function to reclaim its memory.
196
197   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
212         #define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
213         typedef CPL_CHECK_FN(CplCheckFn);
214
215
216
217       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
233
234       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
240
241       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
252   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
258   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
263   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

ATTRIBUTES

270       See attributes(5) for descriptions of the following attributes:
271
272
273
274
275       ┌─────────────────────────────┬─────────────────────────────┐
276       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
277       ├─────────────────────────────┼─────────────────────────────┤
278       │Interface Stability          │Evolving                     │
279       ├─────────────────────────────┼─────────────────────────────┤
280       │MT-Level                     │MT-Safe                      │
281       └─────────────────────────────┴─────────────────────────────┘
282

SEE ALSO

284       cpl_complete_word(3TECLA), ef_expand_file(3TECLA), gl_get_line(3TECLA),
285       libtecla(3LIB), attributes(5)
286
287
288
289SunOS 5.11                        13 Aug 2007          pca_lookup_file(3TECLA)
Impressum