Interactive Command-line Input Library Functions
                                          pcalookupfile(3TECLA)



NAME
     pcalookupfile,       delPathCache,       delPcaPathConf,
     newPathCache,        newPcaPathConf,       pcalasterror,
     pcapathcompletions,    pcascanpath,    pcasetcheckfn,
     ppcfilestart,  ppcliteralescapes  -  lookup  a file in a
     list of directories

SYNOPSIS
     cc [ flag... ] file... -ltecla [ library... ]
     #include 

     char *pcalookupfile(PathCache *pc, const char *name,
          int namelen, int literal);


     PathCache *delPathCache(PathCache *pc);


     PcaPathConf *delPcaPathConf(PcaPathConf *ppc);


     PathCache *newPathCache(void);


     PcaPathConf *newPcaPathConf(PathCache *pc);


     const char *pcalasterror(PathCache *pc);


     CPLMATCHFN(pcapathcompletions);


     int pcascanpath(PathCache *pc, const char *path);


     void pcasetcheckfn(PathCache *pc, CplCheckFn *checkfn,
          void *data);


     void ppcfilestart(PcaPathConf *ppc, int startindex);


     void ppcliteralescapes(PcaPathConf *ppc, int literal);


DESCRIPTION
     The PathCache object is part of the libtecla(3LIB)  library.
     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



SunOS 5.11          Last change: 13 Aug 2007                    1






Interactive Command-line Input Library Functions
                                          pcalookupfile(3TECLA)



     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.

  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 
       #include 
       #include 

       int main(int argc, char *argv[])
       {
               int i;
               /*
               * Create a cache for executable files.
               */
               PathCache *pc = newPathCache();
               if(!pc)
                 exit(1);
               /*
               * Scan the user's PATH for executables.
               */
               if(pcascanpath(pc, getenv("PATH"))) {
                 fprintf(stderr, "%s\n", pcalasterror(pc));
                 exit(1);
               }
               /*
               * Arrange to only report executable files.
               */
               pcasetcheckfn(pc, cplcheckexe, NUL);
               /*
               * Lookup and display the full pathname of each of the
               * commands listed on the command line.
               */
               for(i=1; i