Print this page
12212 typos in some section 3tecla man pages


   7 .\" to whom the Software is furnished to do so, provided that the above
   8 .\" copyright notice(s) and this permission notice appear in all copies of
   9 .\" the Software and that both the above copyright notice(s) and this
  10 .\" permission notice appear in supporting documentation.
  11 .\"
  12 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  13 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  14 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
  15 .\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
  16 .\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
  17 .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
  18 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  19 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  20 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  21 .\"
  22 .\" Except as contained in this notice, the name of a copyright holder
  23 .\" shall not be used in advertising or otherwise to promote the sale, use
  24 .\" or other dealings in this Software without prior written authorization
  25 .\" of the copyright holder.
  26 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
  27 .TH PCA_LOOKUP_FILE 3TECLA "Aug 13, 2007"
  28 .SH NAME
  29 pca_lookup_file, del_PathCache, del_PcaPathConf, new_PathCache,
  30 new_PcaPathConf, pca_last_error, pca_path_completions, pca_scan_path,
  31 pca_set_check_fn, ppc_file_start, ppc_literal_escapes \- lookup a file in a
  32 list of directories
  33 .SH SYNOPSIS
  34 .LP
  35 .nf
  36 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
  37 #include <libtecla.h>
  38 
  39 \fBchar *\fR\fBpca_lookup_file\fR(\fBPathCache *\fR\fIpc\fR, \fBconst char *\fR\fIname\fR,
  40      \fBint\fR \fIname_len\fR, \fBint\fR \fIliteral\fR);
  41 .fi
  42 
  43 .LP
  44 .nf
  45 \fBPathCache *\fR\fBdel_PathCache\fR(\fBPathCache *\fR\fIpc\fR);
  46 .fi
  47 
  48 .LP
  49 .nf
  50 \fBPcaPathConf *\fR\fBdel_PcaPathConf\fR(\fBPcaPathConf *\fR\fIppc\fR);
  51 .fi
  52 
  53 .LP
  54 .nf


  75 \fBint\fR \fBpca_scan_path\fR(\fBPathCache *\fR\fIpc\fR, \fBconst char *\fR\fIpath\fR);
  76 .fi
  77 
  78 .LP
  79 .nf
  80 \fBvoid\fR \fBpca_set_check_fn\fR(\fBPathCache *\fR\fIpc\fR, \fBCplCheckFn *\fR\fIcheck_fn\fR,
  81      \fBvoid *\fR\fIdata\fR);
  82 .fi
  83 
  84 .LP
  85 .nf
  86 \fBvoid\fR \fBppc_file_start\fR(\fBPcaPathConf *\fR\fIppc\fR, \fBint\fR \fIstart_index\fR);
  87 .fi
  88 
  89 .LP
  90 .nf
  91 \fBvoid\fR \fBppc_literal_escapes\fR(\fBPcaPathConf *\fR\fIppc\fR, \fBint\fR \fIliteral\fR);
  92 .fi
  93 
  94 .SH DESCRIPTION
  95 .sp
  96 .LP
  97 The \fBPathCache\fR object is part of the \fBlibtecla\fR(3LIB) library.
  98 \fBPathCache\fR objects allow an application to search for files in any colon
  99 separated list of directories, such as the UNIX execution \fBPATH\fR
 100 environment variable. Files in absolute directories are cached in a
 101 \fBPathCache\fR object, whereas relative directories are scanned as needed.
 102 Using a \fBPathCache\fR object, you can look up the full pathname of a simple
 103 filename, or you can obtain a list of the possible completions of a given
 104 filename prefix. By default all files in the list of directories are targets
 105 for lookup and completion, but a versatile mechanism is provided for only
 106 selecting specific types of files. The obvious application of this facility is
 107 to provide Tab-completion and lookup of executable commands in the UNIX
 108 \fBPATH\fR, so an optional callback which rejects all but executable files, is
 109 provided.
 110 .SS "An Example"
 111 .sp
 112 .LP
 113 Under UNIX, the following example program looks up and displays the full
 114 pathnames of each of the command names on the command line.
 115 .sp
 116 .in +2
 117 .nf
 118 #include <stdio.h>
 119 #include <stdlib.h>
 120 #include <libtecla.h>
 121 
 122 int main(int argc, char *argv[])
 123 {
 124         int i;
 125         /*
 126         * Create a cache for executable files.
 127         */
 128         PathCache *pc = new_PathCache();
 129         if(!pc)
 130           exit(1);
 131         /*
 132         * Scan the user's PATH for executables.


 152         return 0;
 153 }
 154 .fi
 155 .in -2
 156 
 157 .sp
 158 .LP
 159 The following is an example of what this does on a laptop under LINUX:
 160 .sp
 161 .in +2
 162 .nf
 163 $ ./example less more blob
 164 The full pathname of 'less' is /usr/bin/less
 165 The full pathname of 'more' is /bin/more
 166 The full pathname of 'blob' is unknown
 167 $
 168 .fi
 169 .in -2
 170 
 171 .SS "Function Descriptions"
 172 .sp
 173 .LP
 174 To use the facilities of this module, you must first allocate a \fBPathCache\fR
 175 object by calling the \fBnew_PathCache()\fR constructor function. This function
 176 creates the resources needed to cache and lookup files in a list of
 177 directories. It returns \fINULL\fR on error.
 178 .SS "Populating The Cache"
 179 .sp
 180 .LP
 181 Once you have created a cache, it needs to be populated with files. To do this,
 182 call the \fBpca_scan_path()\fR function. Whenever this function is called, it
 183 discards the current contents of the cache, then scans the list of directories
 184 specified in its path argument for files. The path argument must be a string
 185 containing a colon-separated list of directories, such as
 186 "\fB/usr/bin\fR:\fB/home/mcs/bin\fR:". This can include directories specified
 187 by absolute pathnames such as "\fB/usr/bin\fR", as well as sub-directories
 188 specified by relative pathnames such as "." or "\fBbin\fR". Files in the
 189 absolute directories are immediately cached in the specified \fBPathCache\fR
 190 object, whereas subdirectories, whose identities obviously change whenever the
 191 current working directory is changed, are marked to be scanned on the fly
 192 whenever a file is looked up.
 193 .sp
 194 .LP
 195 On success this function return 0. On error it returns 1, and a description of
 196 the error can be obtained by calling \fBpca_last_error\fR(\fIpc\fR).
 197 .SS "Looking Up Files"
 198 .sp
 199 .LP
 200 Once the cache has been populated with files, you can look up the full pathname
 201 of a file, simply by specifying its filename to \fBpca_lookup_file()\fR.
 202 .sp
 203 .LP
 204 To make it possible to pass this function a filename which is actually part of
 205 a longer string, the \fIname_len\fR argument can be used to specify the length
 206 of the filename at the start of the \fIname\fR[] argument. If you pass -1 for
 207 this length, the length of the string will be determined with \fIstrlen\fR. If
 208 the \fIname\fR[] string might contain backslashes that escape the special
 209 meanings of spaces and tabs within the filename, give the \fIliteral\fR
 210 argument the value 0. Otherwise, if backslashes should be treated as normal
 211 characters, pass 1 for the value of the \fIliteral\fR argument.
 212 .SS "Filename Completion"
 213 .sp
 214 .LP
 215 Looking up the potential completions of a filename-prefix in the filename cache
 216 is achieved by passing the provided \fBpca_path_completions()\fR callback
 217 function to the \fBcpl_complete_word\fR(3TECLA) function.
 218 .sp
 219 .LP
 220 This callback requires that its data argument be a pointer to a PcaPathConf
 221 object. Configuration objects of this type are allocated by calling
 222 \fBnew_PcaPathConf()\fR.
 223 .sp
 224 .LP
 225 This function returns an object initialized with default configuration
 226 parameters, which determine how the \fBcpl_path_completions()\fR callback
 227 function behaves. The functions which allow you to individually change these
 228 parameters are discussed below.
 229 .sp
 230 .LP
 231 By default, the \fBpca_path_completions()\fR callback function searches
 232 backwards for the start of the filename being completed, looking for the first
 233 un-escaped space or the start of the input line. If you wish to specify a
 234 different location, call \fBppc_file_start()\fR with the index at which the
 235 filename starts in the input line. Passing \fIstart_index\fR=-1 re-enables the
 236 default behavior.
 237 .sp
 238 .LP
 239 By default, when \fBpca_path_completions()\fR looks at a filename in the input
 240 line, each lone backslash in the input line is interpreted as being a special
 241 character which removes any special significance of the character which follows
 242 it, such as a space which should be taken as part of the filename rather than
 243 delimiting the start of the filename. These backslashes are thus ignored while
 244 looking for completions, and subsequently added before spaces, tabs and literal
 245 backslashes in the list of completions. To have unescaped backslashes treated
 246 as normal characters, call \fBppc_literal_escapes()\fR with a non-zero value in
 247 its literal argument.
 248 .sp
 249 .LP
 250 When you have finished with a \fBPcaPathConf\fR variable, you can pass it to
 251 the \fBdel_PcaPathConf()\fR destructor function to reclaim its memory.
 252 .SS "Being Selective"
 253 .sp
 254 .LP
 255 If you are only interested in certain types or files, such as, for example,
 256 executable files, or files whose names end in a particular suffix, you can
 257 arrange for the file completion and lookup functions to be selective in the
 258 filenames that they return. This is done by registering a callback function
 259 with your \fBPathCache\fR object. Thereafter, whenever a filename is found
 260 which either matches a filename being looked up or matches a prefix which is
 261 being completed, your callback function will be called with the full pathname
 262 of the file, plus any application-specific data that you provide. If the
 263 callback returns 1 the filename will be reported as a match. If it returns 0,
 264 it will be ignored. Suitable callback functions and their prototypes should be
 265 declared with the following macro. The \fBCplCheckFn\fR typedef is also
 266 provided in case you wish to declare pointers to such functions
 267 .sp
 268 .in +2
 269 .nf
 270 #define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
 271 typedef CPL_CHECK_FN(CplCheckFn);
 272 .fi
 273 .in -2
 274 
 275 .sp
 276 .LP
 277 Registering one of these functions involves calling the
 278 \fBpca_set_check_fn()\fR function. In addition to the callback function passed
 279 with the \fIcheck_fn\fR argument, you can pass a pointer to anything with the
 280 \fIdata\fR argument. This pointer will be passed on to your callback function
 281 by its own \fIdata\fR argument whenever it is called, providing a way to pass
 282 application-specific data to your callback. Note that these callbacks are
 283 passed the full pathname of each matching file, so the decision about whether a
 284 file is of interest can be based on any property of the file, not just its
 285 filename. As an example, the provided \fBcpl_check_exe()\fR callback function
 286 looks at the executable permissions of the file and the permissions of its
 287 parent directories, and only returns 1 if the user has execute permission to
 288 the file. This callback function can thus be used to lookup or complete command
 289 names found in the directories listed in the user's \fBPATH\fR environment
 290 variable. The example program above provides a demonstration of this.
 291 .sp
 292 .LP
 293 Beware that if somebody tries to complete an empty string, your callback will
 294 get called once for every file in the cache, which could number in the
 295 thousands. If your callback does anything time consuming, this could result in
 296 an unacceptable delay for the user, so callbacks should be kept short.
 297 .sp
 298 .LP
 299 To improve performance, whenever one of these callbacks is called, the choice
 300 that it makes is cached, and the next time the corresponding file is looked up,
 301 instead of calling the callback again, the cached record of whether it was
 302 accepted or rejected is used. Thus if somebody tries to complete an empty
 303 string, and hits tab a second time when nothing appears to happen, there will
 304 only be one long delay, since the second pass will operate entirely from the
 305 cached dispositions of the files. These cached dipositions are discarded
 306 whenever \fBpca_scan_path()\fR is called, and whenever \fBpca_set_check_fn()\fR
 307 is called with changed callback function or \fIdata\fR arguments.
 308 .SS "Error Handling"
 309 .sp
 310 .LP
 311 If \fBpca_scan_path()\fR reports that an error occurred by returning 1, you can
 312 obtain a terse description of the error by calling
 313 \fBpca_last_error\fR(\fIpc\fR). This returns an internal string containing an
 314 error message.
 315 .SS "Cleaning Up"
 316 .sp
 317 .LP
 318 Once you have finished using a \fBPathCache\fR object, you can reclaim its
 319 resources by passing it to the \fBdel_PathCache()\fR destructor function. This
 320 takes a pointer to one of these objects, and always returns \fINULL\fR.
 321 .SS "Thread Safety"
 322 .sp
 323 .LP
 324 It is safe to use the facilities of this module in multiple threads, provided
 325 that each thread uses a separately allocated \fBPathCache\fR object. In other
 326 words, if two threads want to do path searching, they should each call
 327 \fBnew_PathCache()\fR to allocate their own caches.
 328 .SH ATTRIBUTES
 329 .sp
 330 .LP
 331 See \fBattributes\fR(5) for descriptions of the following attributes:
 332 .sp
 333 
 334 .sp
 335 .TS
 336 box;
 337 c | c
 338 l | l .
 339 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 340 _
 341 Interface Stability     Evolving
 342 _
 343 MT-Level        MT-Safe
 344 .TE
 345 
 346 .SH SEE ALSO
 347 .sp
 348 .LP
 349 \fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA),
 350 \fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB), \fBattributes\fR(5)


   7 .\" to whom the Software is furnished to do so, provided that the above
   8 .\" copyright notice(s) and this permission notice appear in all copies of
   9 .\" the Software and that both the above copyright notice(s) and this
  10 .\" permission notice appear in supporting documentation.
  11 .\"
  12 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  13 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  14 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
  15 .\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
  16 .\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
  17 .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
  18 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  19 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  20 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  21 .\"
  22 .\" Except as contained in this notice, the name of a copyright holder
  23 .\" shall not be used in advertising or otherwise to promote the sale, use
  24 .\" or other dealings in this Software without prior written authorization
  25 .\" of the copyright holder.
  26 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
  27 .TH PCA_LOOKUP_FILE 3TECLA "January 18, 2020"
  28 .SH NAME
  29 pca_lookup_file, del_PathCache, del_PcaPathConf, new_PathCache,
  30 new_PcaPathConf, pca_last_error, pca_path_completions, pca_scan_path,
  31 pca_set_check_fn, ppc_file_start, ppc_literal_escapes \- lookup a file in a
  32 list of directories
  33 .SH SYNOPSIS

  34 .nf
  35 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
  36 #include <libtecla.h>
  37 
  38 \fBchar *\fR\fBpca_lookup_file\fR(\fBPathCache *\fR\fIpc\fR, \fBconst char *\fR\fIname\fR,
  39      \fBint\fR \fIname_len\fR, \fBint\fR \fIliteral\fR);
  40 .fi
  41 
  42 .LP
  43 .nf
  44 \fBPathCache *\fR\fBdel_PathCache\fR(\fBPathCache *\fR\fIpc\fR);
  45 .fi
  46 
  47 .LP
  48 .nf
  49 \fBPcaPathConf *\fR\fBdel_PcaPathConf\fR(\fBPcaPathConf *\fR\fIppc\fR);
  50 .fi
  51 
  52 .LP
  53 .nf


  74 \fBint\fR \fBpca_scan_path\fR(\fBPathCache *\fR\fIpc\fR, \fBconst char *\fR\fIpath\fR);
  75 .fi
  76 
  77 .LP
  78 .nf
  79 \fBvoid\fR \fBpca_set_check_fn\fR(\fBPathCache *\fR\fIpc\fR, \fBCplCheckFn *\fR\fIcheck_fn\fR,
  80      \fBvoid *\fR\fIdata\fR);
  81 .fi
  82 
  83 .LP
  84 .nf
  85 \fBvoid\fR \fBppc_file_start\fR(\fBPcaPathConf *\fR\fIppc\fR, \fBint\fR \fIstart_index\fR);
  86 .fi
  87 
  88 .LP
  89 .nf
  90 \fBvoid\fR \fBppc_literal_escapes\fR(\fBPcaPathConf *\fR\fIppc\fR, \fBint\fR \fIliteral\fR);
  91 .fi
  92 
  93 .SH DESCRIPTION


  94 The \fBPathCache\fR object is part of the \fBlibtecla\fR(3LIB) library.
  95 \fBPathCache\fR objects allow an application to search for files in any colon
  96 separated list of directories, such as the UNIX execution \fBPATH\fR
  97 environment variable. Files in absolute directories are cached in a
  98 \fBPathCache\fR object, whereas relative directories are scanned as needed.
  99 Using a \fBPathCache\fR object, you can look up the full pathname of a simple
 100 filename, or you can obtain a list of the possible completions of a given
 101 filename prefix. By default all files in the list of directories are targets
 102 for lookup and completion, but a versatile mechanism is provided for only
 103 selecting specific types of files. The obvious application of this facility is
 104 to provide Tab-completion and lookup of executable commands in the UNIX
 105 \fBPATH\fR, so an optional callback which rejects all but executable files is
 106 provided.
 107 .SS "An Example"


 108 Under UNIX, the following example program looks up and displays the full
 109 pathnames of each of the command names on the command line.
 110 .sp
 111 .in +2
 112 .nf
 113 #include <stdio.h>
 114 #include <stdlib.h>
 115 #include <libtecla.h>
 116 
 117 int main(int argc, char *argv[])
 118 {
 119         int i;
 120         /*
 121         * Create a cache for executable files.
 122         */
 123         PathCache *pc = new_PathCache();
 124         if(!pc)
 125           exit(1);
 126         /*
 127         * Scan the user's PATH for executables.


 147         return 0;
 148 }
 149 .fi
 150 .in -2
 151 
 152 .sp
 153 .LP
 154 The following is an example of what this does on a laptop under LINUX:
 155 .sp
 156 .in +2
 157 .nf
 158 $ ./example less more blob
 159 The full pathname of 'less' is /usr/bin/less
 160 The full pathname of 'more' is /bin/more
 161 The full pathname of 'blob' is unknown
 162 $
 163 .fi
 164 .in -2
 165 
 166 .SS "Function Descriptions"


 167 To use the facilities of this module, you must first allocate a \fBPathCache\fR
 168 object by calling the \fBnew_PathCache()\fR constructor function. This function
 169 creates the resources needed to cache and lookup files in a list of
 170 directories. It returns \fINULL\fR on error.
 171 .SS "Populating The Cache"


 172 Once you have created a cache, it needs to be populated with files. To do this,
 173 call the \fBpca_scan_path()\fR function. Whenever this function is called, it
 174 discards the current contents of the cache, then scans the list of directories
 175 specified in its path argument for files. The path argument must be a string
 176 containing a colon-separated list of directories, such as
 177 "\fB/usr/bin\fR:\fB/home/mcs/bin\fR:". This can include directories specified
 178 by absolute pathnames such as "\fB/usr/bin\fR", as well as sub-directories
 179 specified by relative pathnames such as "." or "\fBbin\fR". Files in the
 180 absolute directories are immediately cached in the specified \fBPathCache\fR
 181 object, whereas subdirectories, whose identities obviously change whenever the
 182 current working directory is changed, are marked to be scanned on the fly
 183 whenever a file is looked up.
 184 .sp
 185 .LP
 186 On success this function return 0. On error it returns 1, and a description of
 187 the error can be obtained by calling \fBpca_last_error\fR(\fIpc\fR).
 188 .SS "Looking Up Files"


 189 Once the cache has been populated with files, you can look up the full pathname
 190 of a file, simply by specifying its filename to \fBpca_lookup_file()\fR.
 191 .sp
 192 .LP
 193 To make it possible to pass this function a filename which is actually part of
 194 a longer string, the \fIname_len\fR argument can be used to specify the length
 195 of the filename at the start of the \fIname\fR[] argument. If you pass -1 for
 196 this length, the length of the string will be determined with \fIstrlen\fR. If
 197 the \fIname\fR[] string might contain backslashes that escape the special
 198 meanings of spaces and tabs within the filename, give the \fIliteral\fR
 199 argument the value 0. Otherwise, if backslashes should be treated as normal
 200 characters, pass 1 for the value of the \fIliteral\fR argument.
 201 .SS "Filename Completion"


 202 Looking up the potential completions of a filename-prefix in the filename cache
 203 is achieved by passing the provided \fBpca_path_completions()\fR callback
 204 function to the \fBcpl_complete_word\fR(3TECLA) function.
 205 .sp
 206 .LP
 207 This callback requires that its data argument be a pointer to a PcaPathConf
 208 object. Configuration objects of this type are allocated by calling
 209 \fBnew_PcaPathConf()\fR.
 210 .sp
 211 .LP
 212 This function returns an object initialized with default configuration
 213 parameters, which determine how the \fBcpl_path_completions()\fR callback
 214 function behaves. The functions which allow you to individually change these
 215 parameters are discussed below.
 216 .sp
 217 .LP
 218 By default, the \fBpca_path_completions()\fR callback function searches
 219 backwards for the start of the filename being completed, looking for the first
 220 un-escaped space or the start of the input line. If you wish to specify a
 221 different location, call \fBppc_file_start()\fR with the index at which the
 222 filename starts in the input line. Passing \fIstart_index\fR=-1 re-enables the
 223 default behavior.
 224 .sp
 225 .LP
 226 By default, when \fBpca_path_completions()\fR looks at a filename in the input
 227 line, each lone backslash in the input line is interpreted as being a special
 228 character which removes any special significance of the character which follows
 229 it, such as a space which should be taken as part of the filename rather than
 230 delimiting the start of the filename. These backslashes are thus ignored while
 231 looking for completions, and subsequently added before spaces, tabs and literal
 232 backslashes in the list of completions. To have unescaped backslashes treated
 233 as normal characters, call \fBppc_literal_escapes()\fR with a non-zero value in
 234 its literal argument.
 235 .sp
 236 .LP
 237 When you have finished with a \fBPcaPathConf\fR variable, you can pass it to
 238 the \fBdel_PcaPathConf()\fR destructor function to reclaim its memory.
 239 .SS "Being Selective"


 240 If you are only interested in certain types or files, such as, for example,
 241 executable files, or files whose names end in a particular suffix, you can
 242 arrange for the file completion and lookup functions to be selective in the
 243 filenames that they return. This is done by registering a callback function
 244 with your \fBPathCache\fR object. Thereafter, whenever a filename is found
 245 which either matches a filename being looked up or matches a prefix which is
 246 being completed, your callback function will be called with the full pathname
 247 of the file, plus any application-specific data that you provide. If the
 248 callback returns 1 the filename will be reported as a match. If it returns 0,
 249 it will be ignored. Suitable callback functions and their prototypes should be
 250 declared with the following macro. The \fBCplCheckFn\fR typedef is also
 251 provided in case you wish to declare pointers to such functions.
 252 .sp
 253 .in +2
 254 .nf
 255 #define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
 256 typedef CPL_CHECK_FN(CplCheckFn);
 257 .fi
 258 .in -2
 259 
 260 .sp
 261 .LP
 262 Registering one of these functions involves calling the
 263 \fBpca_set_check_fn()\fR function. In addition to the callback function passed
 264 with the \fIcheck_fn\fR argument, you can pass a pointer to anything with the
 265 \fIdata\fR argument. This pointer will be passed on to your callback function
 266 by its own \fIdata\fR argument whenever it is called, providing a way to pass
 267 application-specific data to your callback. Note that these callbacks are
 268 passed the full pathname of each matching file, so the decision about whether a
 269 file is of interest can be based on any property of the file, not just its
 270 filename. As an example, the provided \fBcpl_check_exe()\fR callback function
 271 looks at the executable permissions of the file and the permissions of its
 272 parent directories, and only returns 1 if the user has execute permission to
 273 the file. This callback function can thus be used to lookup or complete command
 274 names found in the directories listed in the user's \fBPATH\fR environment
 275 variable. The example program above provides a demonstration of this.
 276 .sp
 277 .LP
 278 Beware that if somebody tries to complete an empty string, your callback will
 279 get called once for every file in the cache, which could number in the
 280 thousands. If your callback does anything time consuming, this could result in
 281 an unacceptable delay for the user, so callbacks should be kept short.
 282 .sp
 283 .LP
 284 To improve performance, whenever one of these callbacks is called, the choice
 285 that it makes is cached, and the next time the corresponding file is looked up,
 286 instead of calling the callback again, the cached record of whether it was
 287 accepted or rejected is used. Thus if somebody tries to complete an empty
 288 string, and hits tab a second time when nothing appears to happen, there will
 289 only be one long delay, since the second pass will operate entirely from the
 290 cached dispositions of the files. These cached dispositions are discarded
 291 whenever \fBpca_scan_path()\fR is called, and whenever \fBpca_set_check_fn()\fR
 292 is called with changed callback function or \fIdata\fR arguments.
 293 .SS "Error Handling"


 294 If \fBpca_scan_path()\fR reports that an error occurred by returning 1, you can
 295 obtain a terse description of the error by calling
 296 \fBpca_last_error\fR(\fIpc\fR). This returns an internal string containing an
 297 error message.
 298 .SS "Cleaning Up"


 299 Once you have finished using a \fBPathCache\fR object, you can reclaim its
 300 resources by passing it to the \fBdel_PathCache()\fR destructor function. This
 301 takes a pointer to one of these objects, and always returns \fINULL\fR.
 302 .SS "Thread Safety"


 303 It is safe to use the facilities of this module in multiple threads, provided
 304 that each thread uses a separately allocated \fBPathCache\fR object. In other
 305 words, if two threads want to do path searching, they should each call
 306 \fBnew_PathCache()\fR to allocate their own caches.
 307 .SH ATTRIBUTES


 308 See \fBattributes\fR(5) for descriptions of the following attributes:
 309 .sp
 310 
 311 .sp
 312 .TS
 313 box;
 314 c | c
 315 l | l .
 316 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 317 _
 318 Interface Stability     Evolving
 319 _
 320 MT-Level        MT-Safe
 321 .TE
 322 
 323 .SH SEE ALSO


 324 \fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA),
 325 \fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB), \fBattributes\fR(5)