NAME

complete − file name completion

SYNOPSIS

­#include <u.h>
­#include <libc.h>
­#include <complete.h>

typedef struct Completion Completion;
struct Completion{
uchar advance; /∗ whether forward progress has been made ∗/
uchar complete; /∗ whether the completion now represents a file or directory ∗/
char ∗string; /∗ the string to advance, suffixed " " or "/" for file or directory ∗/
int nmatch; /∗ number of files that matched ∗/
int nfile; /∗ number of files returned ∗/
char ∗∗filename; /∗ their names ∗/
};
 

Completion∗ complete(char ∗dir, char ∗s);

void freecompletion(Completion ∗c);

DESCRIPTION

The ­complete function implements file name completion.  Given a directory ­dir and a string s, it returns an analysis of the file names in that directory that begin with the string s. The fields ­nmatch and ­nfile will be set to the number of files that match the prefix and ­filename will be filled in with their names.  If the file named is a directory, a slash character will be appended to it. 

If no files match the string, ­nmatch will be zero, but ­complete will return the full set of files in the directory, with ­nfile set to their number. 

The flag ­advance reports whether the string ­s can be extended without changing the set of files that match.  If true, ­string will be set to the extension; that is, the value of ­string may be appended to ­s by the caller to extend the embryonic file name unambiguously. 

The flag ­complete reports whether the extended file name uniquely identifies a file.  If true, ­string will be suffixed with a blank, or a slash and a blank, depending on whether the resulting file name identifies a plain file or a directory. 

The ­freecompletion function frees a ­Completion structure and its contents. 

In rio(1) and acme(1), file name completion is triggered by a control-F character or an Insert character.

SOURCE

­/sys/src/libcomplete

SEE ALSO

rio(1), acme(1)

DIAGNOSTICS

The ­complete function returns a null pointer and sets ­errstr if the directory is unreadable or there is some other error. 

BUGS

The behavior of file name completion should be controlled by the plumber. 

Plan 9  —  February 08, 2004