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.