.\" Copyright (C) 2001 by Martin C. Shepherd.\" .\" All rights reserved..\" .\" Permission is hereby granted, free of charge, to any person obtaining a.\" copy of this software and associated documentation files (the.\" "Software"), to deal in the Software without restriction, including.\" without limitation the rights to use, copy, modify, merge, publish,.\" distribute, and/or sell copies of the Software, and to permit persons.\" to whom the Software is furnished to do so, provided that the above.\" copyright notice(s) and this permission notice appear in all copies of.\" the Software and that both the above copyright notice(s) and this.\" permission notice appear in supporting documentation..\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE..\" .\" Except as contained in this notice, the name of a copyright holder.\" shall not be used in advertising or otherwise to promote the sale, use.\" or other dealings in this Software without prior written authorization.\" of the copyright holder..TH pca_lookup_file 3.SH NAMEpca_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.SH SYNOPSIS.nf#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);.fi.SH DESCRIPTIONThe \f3PathCache\f1 object is part of the tecla library (see thelibtecla(3) man page)..sp\f3PathCache\f1 objects allow an application to search for files inany colon separated list of directories, such as the unix executionPATH environment variable. Files in absolute directories are cached ina \f3PathCache\f1 object, whereas relative directories are scanned asneeded. Using a \f3PathCache\f1 object, you can look up the fullpathname of a simple filename, or you can obtain a list of thepossible completions of a given filename prefix. By default all filesin the list of directories are targets for lookup and completion, buta versatile mechanism is provided for only selecting specific types offiles. The obvious application of this facility is to provideTab-completion and lookup of executable commands in the unix PATH, soan optional callback which rejects all but executable files, isprovided..sp.SH AN EXAMPLEUnder UNIX, the following example program looks up and displays thefull pathnames of each of the command names on the command line..sp.nf  #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;  }.fi.spThe following is an example of what this does on my laptop underlinux:.sp.nf  $ ./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  $ .fi.sp.SH FUNCTION DESCRIPTIONSIn order to use the facilities of this module, you must first allocatea \f3PathCache\f1 object by calling the \f3new_PathCache()\f1constructor function..sp.nf  PathCache *new_PathCache(void).fi.spThis function creates the resources needed to cache and lookup filesin a list of directories. It returns \f3NULL\f1 on error..sp.SH POPULATING THE CACHEOnce you have created a cache, it needs to be populated with files.To do this, call the \f3pca_scan_path()\f1 function..sp.nf  int pca_scan_path(PathCache *pc, const char *path);.fi.spWhenever this function is called, it discards the current contents ofthe cache, then scans the list of directories specified in its\f3path\f1 argument for files. The \f3path\f1 argument must be astring containing a colon-separated list of directories, such as\f3"/usr/bin:/home/mcs/bin:."\f1. This can include directoriesspecified by absolute pathnames such as \f3"/usr/bin"\f1, as well assub-directories specified by relative pathnames such as \f3"."\f1 or\f3"bin"\f1. Files in the absolute directories are immediately cachedin the specified \f3PathCache\f1 object, whereas sub-directories,whose identities obviously change whenever the current workingdirectory is changed, are marked to be scanned on the fly whenever afile is looked up..spOn success this function return \f30\f1. On error it returns \f31\f1,and a description of the error can be obtained by calling\f3pca_last_error(pc)\f1..sp.SH LOOKING UP FILESOnce the cache has been populated with files, you can look up the fullpathname of a file, simply by specifying its filename to\f3pca_lookup_file()\f1..sp.nf  char *pca_lookup_file(PathCache *pc, const char *name,                        int name_len, int literal);.fi.spTo make it possible to pass this function a filename which is actuallypart of a longer string, the \f3name_len\f1 argument can be used tospecify the length of the filename at the start of the \f3name[]\f1argument. If you pass \f3-1\f1 for this length, the length of thestring will be determined with \f3strlen()\f1. If the \f3name[]\f1string might contain backslashes that escape the special meanings ofspaces and tabs within the filename, give the \f3literal\f1 argument,the value \f30\f1. Otherwise, if backslashes should be treated asnormal characters, pass \f31\f1 for the value of the \f3literal\f1argument..SH FILENAME COMPLETIONLooking up the potential completions of a filename-prefix in thefilename cache, is achieved by passing the provided\f3pca_path_completions()\f1 callback function to the\f3cpl_complete_word()\f1 function (see the \f3cpl_complete_word(3)\f1man page)..sp.nf  CPL_MATCH_FN(pca_path_completions);.fi.spThis callback requires that its \f3data\f1 argument be a pointer to a\f3PcaPathConf\f1 object. Configuration objects of this type areallocated by calling \f3new_PcaPathConf()\f1..sp.nf  PcaPathConf *new_PcaPathConf(PathCache *pc);.fi.spThis function returns an object initialized with default configurationparameters, which determine how the \f3cpl_path_completions()\f1callback function behaves. The functions which allow you toindividually change these parameters are discussed below..spBy default, the \f3pca_path_completions()\f1 callback functionsearches backwards for the start of the filename being completed,looking for the first un-escaped space or the start of the inputline. If you wish to specify a different location, call\f3ppc_file_start()\f1 with the index at which the filename starts inthe input line. Passing \f3start_index=-1\f1 re-enables the defaultbehavior..sp.nf  void ppc_file_start(PcaPathConf *ppc, int start_index);.fi.spBy default, when \f3pca_path_completions()\f1 looks at a filename inthe input line, each lone backslash in the input line is interpretedas being a special character which removes any special significance ofthe character which follows it, such as a space which should be takenas part of the filename rather than delimiting the start of thefilename. These backslashes are thus ignored while looking forcompletions, and subsequently added before spaces, tabs and literalbackslashes in the list of completions. To have unescaped backslashestreated as normal characters, call \f3ppc_literal_escapes()\f1 with anon-zero value in its \f3literal\f1 argument..sp.nf  void ppc_literal_escapes(PcaPathConf *ppc, int literal);.fi.spWhen you have finished with a \f3PcaPathConf\f1 variable, you can passit to the \f3del_PcaPathConf()\f1 destructor function to reclaim itsmemory..sp.nf  PcaPathConf *del_PcaPathConf(PcaPathConf *ppc);.fi.sp.SH BEING SELECTIVEIf you are only interested in certain types or files, such as, forexample, executable files, or files whose names end in a particularsuffix, you can arrange for the file completion and lookup functionsto be selective in the filenames that they return.  This is done byregistering a callback function with your \f3PathCache\f1object. Thereafter, whenever a filename is found which either matchesa filename being looked up, or matches a prefix which is beingcompleted, your callback function will be called with the fullpathname of the file, plus any application-specific data that youprovide, and if the callback returns \f31\f1 the filename will bereported as a match, and if it returns \f30\f1, it will be ignored.Suitable callback functions and their prototypes should be declaredwith the following macro. The \f3CplCheckFn\f1 \f3typedef\f1 is alsoprovided in case you wish to declare pointers to such functions..sp.nf  #define CPL_CHECK_FN(fn) int (fn)(void *data, \\                                    const char *pathname)  typedef CPL_CHECK_FN(CplCheckFn);.fi.spRegistering one of these functions involves calling the\f3pca_set_check_fn()\f1 function. In addition to the callbackfunction, passed via the \f3check_fn\f1 argument, you can pass apointer to anything via the \f3data\f1 argument. This pointer will bepassed on to your callback function, via its own \f3data\f1 argument,whenever it is called, so this provides a way to pass appplicationspecific data to your callback..sp.nf  void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn,                        void *data);.fi.spNote that these callbacks are passed the full pathname of eachmatching file, so the decision about whether a file is of interest canbe based on any property of the file, not just its filename. As anexample, the provided \f3cpl_check_exe()\f1 callback function looks atthe executable permissions of the file and the permissions of itsparent directories, and only returns \f31\f1 if the user has executepermission to the file. This callback function can thus be used tolookup or complete command names found in the directories listed inthe user's \f3PATH\f1 environment variable. The example program givenearlier in this man page provides a demonstration of this..spBeware that if somebody tries to complete an empty string, yourcallback will get called once for every file in the cache, which couldnumber in the thousands. If your callback does anything timeconsuming, this could result in an unacceptable delay for the user, socallbacks should be kept short..spTo improve performance, whenever one of these callbacks is called, thechoice that it makes is cached, and the next time the correspondingfile is looked up, instead of calling the callback again, the cachedrecord of whether it was accepted or rejected is used. Thus ifsomebody tries to complete an empty string, and hits tab a second timewhen nothing appears to happen, there will only be one long delay,since the second pass will operate entirely from the cacheddispositions of the files. These cached dipositions are discardedwhenever \f3pca_scan_path()\f1 is called, and whenever\f3pca_set_check_fn()\f1 is called with changed callback function ordata arguments..SH ERROR HANDLINGIf \f3pca_scan_path()\f1 reports that an error occurred by returning\f31\f1, you can obtain a terse description of the error by calling\f3pca_last_error(pc)\f1. This returns an internal string containingan error message..sp.nf  const char *pca_last_error(PathCache *pc);.fi.sp.SH CLEANING UPOnce you have finished using a \f3PathCache\f1 object, you can reclaimits resources by passing it to the \f3del_PathCache()\f1 destructorfunction. This takes a pointer to one of these objects, and alwaysreturns \f3NULL\f1..sp.nf  PathCache *del_PathCache(PathCache *pc);.fi.sp.SH THREAD SAFETYIn multi-threaded programs, you should use the \f3libtecla_r.a\f1version of the library. This uses POSIX reentrant functions whereavailable (hence the \f3_r\f1 suffix), and disables features that relyon non-reentrant system functions. In the case of this module, theonly disabled feature is username completion in \f3~username/\f1expressions, in \f3cpl_path_completions()\f1.Using the \f3libtecla_r.a\f1 version of the library, it is safe to usethe facilities of this module in multiple threads, provided that eachthread uses a separately allocated \f3PathCache\f1 object. In otherwords, if two threads want to do path searching, they should each call\f3new_PathCache()\f1 to allocate their own caches..SH FILES.nflibtecla.a    -    The tecla librarylibtecla.h    -    The tecla header file..fi.SH SEE ALSOlibtecla(3), gl_get_line(3), ef_expand_file(3), cpl_complete_word(3)  .SH AUTHORMartin Shepherd  (mcs@astro.caltech.edu)