Provided by: libtecla-dev_1.6.3-2_amd64 
NAME
pca_lookup_file, del_PathCache, del_PcaPathConf, new_PathCache, new_PcaPathConf,
pca_last_error, pca_path_completions, pca_scan_path, pca_set_check_fn, ppc_file_start,
ppc_literal_escapes - lookup a file in a list of directories
SYNOPSIS
#include <libtecla.h>
PathCache *new_PathCache(void);
PathCache *del_PathCache(PathCache *pc);
int pca_scan_path(PathCache *pc, const char *path);
void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn,
void *data);
char *pca_lookup_file(PathCache *pc, const char *name,
int name_len, int literal);
const char *pca_last_error(PathCache *pc);
CPL_MATCH_FN(pca_path_completions);
DESCRIPTION
The PathCache object is part of the tecla library (see the libtecla(3) man page).
PathCache objects allow an application to search for files in any colon separated list of
directories, such as the unix execution PATH environment variable. Files in absolute
directories are cached in a PathCache object, whereas relative directories are scanned as
needed. Using a PathCache object, you can look up the full pathname of a simple filename,
or you can obtain a list of the possible completions of a given filename prefix. By
default all files in the list of directories are targets for lookup and completion, but a
versatile mechanism is provided for only selecting specific types of files. The obvious
application of this facility is to provide Tab-completion and lookup of executable
commands in the unix PATH, so an optional callback which rejects all but executable files,
is provided.
AN EXAMPLE
Under UNIX, the following example program looks up and displays the full pathnames of each
of the command names on the command line.
#include <stdio.h>
#include <stdlib.h>
#include <libtecla.h>
int main(int argc, char *argv[])
{
int i;
/*
* Create a cache for executable files.
*/
PathCache *pc = new_PathCache();
if(!pc)
exit(1);
/*
* Scan the user's PATH for executables.
*/
if(pca_scan_path(pc, getenv("PATH"))) {
fprintf(stderr, "%s\n", pca_last_error(pc));
exit(1);
}
/*
* Arrange to only report executable files.
*/
pca_set_check_fn(pc, cpl_check_exe, NULL);
/*
* Lookup and display the full pathname of each of the
* commands listed on the command line.
*/
for(i=1; i<argc; i++) {
char *cmd = pca_lookup_file(pc, argv[i], -1, 0);
printf("The full pathname of '%s' is %s\n", argv[i],
cmd ? cmd : "unknown");
}
pc = del_PathCache(pc); /* Clean up */
return 0;
}
The following is an example of what this does on my laptop under linux:
$ ./example less more blob
The full pathname of 'less' is /usr/bin/less
The full pathname of 'more' is /bin/more
The full pathname of 'blob' is unknown
$
FUNCTION DESCRIPTIONS
In order to use the facilities of this module, you must first allocate a PathCache object
by calling the new_PathCache() constructor function.
PathCache *new_PathCache(void)
This function creates the resources needed to cache and lookup files in a list of
directories. It returns NULL on error.
POPULATING THE CACHE
Once you have created a cache, it needs to be populated with files. To do this, call the
pca_scan_path() function.
int pca_scan_path(PathCache *pc, const char *path);
Whenever this function is called, it discards the current contents of the cache, then
scans the list of directories specified in its path argument for files. The path argument
must be a string containing a colon-separated list of directories, such as
"/usr/bin:/home/mcs/bin:.". This can include directories specified by absolute pathnames
such as "/usr/bin", as well as sub-directories specified by relative pathnames such as "."
or "bin". Files in the absolute directories are immediately cached in the specified
PathCache object, whereas sub-directories, whose identities obviously change whenever the
current working directory is changed, are marked to be scanned on the fly whenever a file
is looked up.
On success this function return 0. On error it returns 1, and a description of the error
can be obtained by calling pca_last_error(pc).
LOOKING UP FILES
Once the cache has been populated with files, you can look up the full pathname of a file,
simply by specifying its filename to pca_lookup_file().
char *pca_lookup_file(PathCache *pc, const char *name,
int name_len, int literal);
To make it possible to pass this function a filename which is actually part of a longer
string, the name_len argument can be used to specify the length of the filename at the
start of the name[] argument. If you pass -1 for this length, the length of the string
will be determined with strlen(). If the name[] string might contain backslashes that
escape the special meanings of spaces and tabs within the filename, give the literal
argument, the value 0. Otherwise, if backslashes should be treated as normal characters,
pass 1 for the value of the literal argument.
FILENAME COMPLETION
Looking up the potential completions of a filename-prefix in the filename cache, is
achieved by passing the provided pca_path_completions() callback function to the
cpl_complete_word() function (see the cpl_complete_word(3) man page).
CPL_MATCH_FN(pca_path_completions);
This callback requires that its data argument be a pointer to a PcaPathConf object.
Configuration objects of this type are allocated by calling new_PcaPathConf().
PcaPathConf *new_PcaPathConf(PathCache *pc);
This function returns an object initialized with default configuration parameters, which
determine how the cpl_path_completions() callback function behaves. The functions which
allow you to individually change these parameters are discussed below.
By default, the pca_path_completions() callback function searches backwards for the start
of the filename being completed, looking for the first un-escaped space or the start of
the input line. If you wish to specify a different location, call ppc_file_start() with
the index at which the filename starts in the input line. Passing start_index=-1 re-
enables the default behavior.
void ppc_file_start(PcaPathConf *ppc, int start_index);
By default, when pca_path_completions() looks at a filename in the input line, each lone
backslash in the input line is interpreted as being a special character which removes any
special significance of the character which follows it, such as a space which should be
taken as part of the filename rather than delimiting the start of the filename. These
backslashes are thus ignored while looking for completions, and subsequently added before
spaces, tabs and literal backslashes in the list of completions. To have unescaped
backslashes treated as normal characters, call ppc_literal_escapes() with a non-zero value
in its literal argument.
void ppc_literal_escapes(PcaPathConf *ppc, int literal);
When you have finished with a PcaPathConf variable, you can pass it to the
del_PcaPathConf() destructor function to reclaim its memory.
PcaPathConf *del_PcaPathConf(PcaPathConf *ppc);
BEING SELECTIVE
If you are only interested in certain types or files, such as, for example, executable
files, or files whose names end in a particular suffix, you can arrange for the file
completion and lookup functions to be selective in the filenames that they return. This
is done by registering a callback function with your PathCache object. Thereafter,
whenever a filename is found which either matches a filename being looked up, or matches a
prefix which is being completed, your callback function will be called with the full
pathname of the file, plus any application-specific data that you provide, and if the
callback returns 1 the filename will be reported as a match, and if it returns 0, it will
be ignored. Suitable callback functions and their prototypes should be declared with the
following macro. The CplCheckFn typedef is also provided in case you wish to declare
pointers to such functions.
#define CPL_CHECK_FN(fn) int (fn)(void *data, \
const char *pathname)
typedef CPL_CHECK_FN(CplCheckFn);
Registering one of these functions involves calling the pca_set_check_fn() function. In
addition to the callback function, passed via the check_fn argument, you can pass a
pointer to anything via the data argument. This pointer will be passed on to your callback
function, via its own data argument, whenever it is called, so this provides a way to pass
appplication specific data to your callback.
void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn,
void *data);
Note that these callbacks are passed the full pathname of each matching file, so the
decision about whether a file is of interest can be based on any property of the file, not
just its filename. As an example, the provided cpl_check_exe() callback function looks at
the executable permissions of the file and the permissions of its parent directories, and
only returns 1 if the user has execute permission to the file. This callback function can
thus be used to lookup or complete command names found in the directories listed in the
user's PATH environment variable. The example program given earlier in this man page
provides a demonstration of this.
Beware that if somebody tries to complete an empty string, your callback will get called
once for every file in the cache, which could number in the thousands. If your callback
does anything time consuming, this could result in an unacceptable delay for the user, so
callbacks should be kept short.
To improve performance, whenever one of these callbacks is called, the choice that it
makes is cached, and the next time the corresponding file is looked up, instead of calling
the callback again, the cached record of whether it was accepted or rejected is used. Thus
if somebody tries to complete an empty string, and hits tab a second time when nothing
appears to happen, there will only be one long delay, since the second pass will operate
entirely from the cached dispositions of the files. These cached dipositions are discarded
whenever pca_scan_path() is called, and whenever pca_set_check_fn() is called with changed
callback function or data arguments.
ERROR HANDLING
If pca_scan_path() reports that an error occurred by returning 1, you can obtain a terse
description of the error by calling pca_last_error(pc). This returns an internal string
containing an error message.
const char *pca_last_error(PathCache *pc);
CLEANING UP
Once you have finished using a PathCache object, you can reclaim its resources by passing
it to the del_PathCache() destructor function. This takes a pointer to one of these
objects, and always returns NULL.
PathCache *del_PathCache(PathCache *pc);
THREAD SAFETY
In multi-threaded programs, you should use the libtecla_r.a version of the library. This
uses POSIX reentrant functions where available (hence the _r suffix), and disables
features that rely on non-reentrant system functions. In the case of this module, the only
disabled feature is username completion in ~username/ expressions, in
cpl_path_completions().
Using the libtecla_r.a version of the library, it is safe to use the facilities of this
module in multiple threads, provided that each thread uses a separately allocated
PathCache object. In other words, if two threads want to do path searching, they should
each call new_PathCache() to allocate their own caches.
FILES
libtecla.a - The tecla library
libtecla.h - The tecla header file.
SEE ALSO
libtecla(3), gl_get_line(3), ef_expand_file(3),
cpl_complete_word(3)
AUTHOR
Martin Shepherd (mcs@astro.caltech.edu)
pca_lookup_file(3)