Provided by: libtecla1-dev_1.6.1-5_i386 bug

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)