| rsc | cfa37a7 | 2004-04-10 18:53:55 +0000 | [diff] [blame] | 1 | .TH COMPLETE 3 |
| 2 | .SH NAME |
| rsc | 058b011 | 2005-01-03 06:40:20 +0000 | [diff] [blame] | 3 | complete, freecompletion \- file name completion |
| rsc | cfa37a7 | 2004-04-10 18:53:55 +0000 | [diff] [blame] | 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; /* whether forward progress has been made */ |
| 17 | uchar complete; /* whether the completion now represents a file or directory */ |
| 18 | char *string; /* the string to advance, suffixed " " or "/" for file or directory */ |
| 19 | int nmatch; /* number of files that matched */ |
| 20 | int nfile; /* number of files returned */ |
| 21 | char **filename; /* their names */ |
| 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 | .IR rio (1) |
| 90 | and |
| 91 | .IR acme (1), |
| 92 | file name completion is triggered by a control-F character or an Insert character. |
| 93 | .SH SOURCE |
| rsc | c3674de | 2005-01-11 17:37:33 +0000 | [diff] [blame] | 94 | .B \*9/src/libcomplete |
| rsc | cfa37a7 | 2004-04-10 18:53:55 +0000 | [diff] [blame] | 95 | .SH SEE ALSO |
| 96 | .IR rio (1), |
| 97 | .IR 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. |
