cc [ flag... ] file... -ltecla [ library... ]
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 */
SunOS 5.11 Last change: 13 Aug 2007 2
Interactive Command-line Input Library Functions
pca_lookup_file(3TECLA)
return 0;
}
The following is an example of what this does on a 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
To use the facilities of this module, you must first allo-
cate a PathCache object by calling the new_PathCache() con-
structor function. 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. When-
ever this function is called, it discards the current con-
tents 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 direc-
tories, 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 direc-
tories are immediately cached in the specified PathCache
object, whereas subdirectories, 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().
SunOS 5.11 Last change: 13 Aug 2007 3
Interactive Command-line Input Library Functions
pca_lookup_file(3TECLA)
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(3TECLA) function.
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().
This function returns an object initialized with default
configuration parameters, which determine how the
cpl_path_completions() callback function behaves. The func-
tions which allow you to individually change these parame-
ters are discussed below.
By default, the pca_path_completions() callback function
searches backwards for the start of the filename being com-
pleted, looking for the first un-escaped space or the start
of the input line. If you wish to specify a different loca-
tion, 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.
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.
SunOS 5.11 Last change: 13 Aug 2007 4
Interactive Command-line Input Library Functions
pca_lookup_file(3TECLA)
When you have finished with a PcaPathConf variable, you can
pass it to the del_PcaPathConf() destructor function to
reclaim its memory.
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 comple-
tion 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 pro-
vide. If the callback returns 1 the filename will be
reported as a match. 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 with the check_fn argument, you can pass a
pointer to anything with the data argument. This pointer
will be passed on to your callback function by its own data
argument whenever it is called, providing a way to pass
application-specific data to your callback. 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() call-
back 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 com-
plete command names found in the directories listed in the
user's PATH environment variable. The example program above
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
SunOS 5.11 Last change: 13 Aug 2007 5
Interactive Command-line Input Library Functions
pca_lookup_file(3TECLA)
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 com-
plete an empty string, and hits tab a second time when noth-
ing 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 dis-
carded 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 return-
ing 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.
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.
Thread Safety
It is safe to use the facilities of this module in multiple
threads, provided that each thread uses a separately allo-
cated PathCache object. In other words, if two threads want
to do path searching, they should each call new_PathCache()
to allocate their own caches.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 13 Aug 2007 6
Interactive Command-line Input Library Functions
pca_lookup_file(3TECLA)
______________________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
cpl_complete_word(3TECLA), ef_expand_file(3TECLA),
gl_get_line(3TECLA), libtecla(3LIB), attributes(5)
SunOS 5.11 Last change: 13 Aug 2007 7
Interactive Command-line Input Library Functions
pca_lookup_file(3TECLA)
SunOS 5.11 Last change: 13 Aug 2007 8