diff options
Diffstat (limited to 'libtecla-1.4.1/html/pca_lookup_file.html')
| -rw-r--r-- | libtecla-1.4.1/html/pca_lookup_file.html | 371 |
1 files changed, 0 insertions, 371 deletions
diff --git a/libtecla-1.4.1/html/pca_lookup_file.html b/libtecla-1.4.1/html/pca_lookup_file.html deleted file mode 100644 index 40c9f2b..0000000 --- a/libtecla-1.4.1/html/pca_lookup_file.html +++ /dev/null @@ -1,371 +0,0 @@ -<head> -<title>Manual Page</title> -</head> -<body> -<pre> -</pre><h2>NAME</h2><pre> - 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 - -</pre><h2>SYNOPSIS</h2><pre> - #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); - - - -</pre><h2>DESCRIPTION</h2><pre> - The PathCache object is part of the tecla library (see the - <a href="libtecla.html">libtecla(3)</a> 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 rela- - tive 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 comple- - tions of a given filename prefix. By default all files in - the list of directories are targets for lookup and comple- - tion, but a versatile mechanism is provided for only select- - ing specific types of files. The obvious application of this - facility is to provide Tab-completion and lookup of execut- - able commands in the unix PATH, so an optional callback - which rejects all but executable files, is provided. - - -</pre><h2>AN EXAMPLE</h2><pre> - 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 - $ - - -</pre><h2>FUNCTION DESCRIPTIONS</h2><pre> - 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. - - -</pre><h2>POPULATING THE CACHE</h2><pre> - 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 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 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). - - -</pre><h2>LOOKING UP FILES</h2><pre> - 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. Other- - wise, if backslashes should be treated as normal characters, - pass 1 for the value of the literal argument. - - -</pre><h2>FILENAME COMPLETION</h2><pre> - 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 <a href="cpl_complete_word.html">cpl_complete_word(3)</a> - 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 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. - - 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); - -</pre><h2>BEING SELECTIVE</h2><pre> - 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 - 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 per- - mission 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 demonstra- - tion 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 unac- - ceptable 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. - - -</pre><h2>ERROR HANDLING</h2><pre> - 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. - - const char *pca_last_error(PathCache *pc); - - - -</pre><h2>CLEANING UP</h2><pre> - 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); - - -</pre><h2>THREAD SAFETY</h2><pre> - 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 comple- - tion 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, pro- - vided 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. - - -</pre><h2>FILES</h2><pre> - libtecla.a - The tecla library - libtecla.h - The tecla header file. -</pre><h2>SEE ALSO</h2><pre> - <a href="libtecla.html">libtecla(3)</a>, <a href="gl_get_line.html">gl_get_line(3)</a>, <a href="ef_expand_file.html">ef_expand_file(3)</a>, - <a href="cpl_complete_word.html">cpl_complete_word(3)</a> - - -</pre><h2>AUTHOR</h2><pre> - Martin Shepherd (mcs@astro.caltech.edu) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</pre> -</body> |