complete.3 (2144B)
1 .TH COMPLETE 3 2 .SH NAME 3 complete, freecompletion \- file name completion 4 .SH SYNOPSIS 5 .B #include <u.h> 6 .br 7 .B #include <libc.h> 8 .br 9 .B #include <complete.h> 10 .PP 11 .ft L 12 .nf 13 .ta \w' 'u +\w' 'u +\w' 'u +\w' 'u +\w' 'u 14 typedef struct Completion Completion; 15 struct Completion{ 16 uchar advance; 17 uchar complete; 18 char *string; 19 int nmatch; 20 int nfile; 21 char **filename; 22 }; 23 24 .fi 25 .PP 26 .B 27 .ta \w'\fLchar* 'u 28 29 .PP 30 .B 31 Completion* complete(char *dir, char *s); 32 .PP 33 .B 34 void freecompletion(Completion *c); 35 .SH DESCRIPTION 36 The 37 .I complete 38 function implements file name completion. 39 Given a directory 40 .I dir 41 and a string 42 .IR s , 43 it returns an analysis of the file names in that directory that begin with the string 44 .IR s . 45 The fields 46 .B nmatch 47 and 48 .B nfile 49 will be set to the number of files that match the prefix and 50 .B filename 51 will be filled in with their names. 52 If the file named is a directory, a slash character will be appended to it. 53 .PP 54 If no files match the string, 55 .B nmatch 56 will be zero, but 57 .I complete 58 will return the full set of files in the directory, with 59 .I nfile 60 set to their number. 61 .PP 62 The flag 63 .B advance 64 reports whether the string 65 .I s 66 can be extended without changing the set of files that match. If true, 67 .B string 68 will be set to the extension; that is, the value of 69 .B string 70 may be appended to 71 .I s 72 by the caller to extend the embryonic file name unambiguously. 73 .PP 74 The flag 75 .B complete 76 reports whether the extended file name uniquely identifies a file. 77 If true, 78 .B string 79 will be suffixed with a blank, or a slash and a blank, 80 depending on whether the resulting file name identifies a plain file or a directory. 81 .PP 82 The 83 .I freecompletion 84 function frees a 85 .B Completion 86 structure and its contents. 87 .PP 88 In 89 .MR rio (1) 90 and 91 .MR acme (1) , 92 file name completion is triggered by a control-F character or an Insert character. 93 .SH SOURCE 94 .B \*9/src/libcomplete 95 .SH SEE ALSO 96 .MR rio (1) , 97 .MR acme (1) 98 .SH DIAGNOSTICS 99 The 100 .I complete 101 function returns a null pointer and sets 102 .I errstr 103 if the directory is unreadable or there is some other error. 104 .SH BUGS 105 The behavior of file name completion should be controlled by the plumber.