COMPLETE(2)                                           COMPLETE(2)

     NAME
          complete - file name completion

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

          typedef struct CompletionCompletion;
          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 direc-
          tory, 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 suf-
          fixed 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.

     Page 1                       Plan 9             (printed 3/28/24)

     COMPLETE(2)                                           COMPLETE(2)

          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.

     Page 2                       Plan 9             (printed 3/28/24)