GNU Dictionary Server
7 Dico — a client program.
dico program is a console-based utility for querying
dictionary servers. It has two operation modes. In single query
mode, the utility performs a query, displays its result and exits
immediately. This mode is entered if a word or a URL was
given in the command line. In interactive mode, the utility
enters a read-and-eval loop, in which it reads requests from the
keyboard, performs the necessary searches, and displays obtained
results on the screen.
7.1 Single Query Mode
The simplest way to use
dico utility is to invoke it with
a word as an argument, e.g.:
$ dico entdeckung
In the example above, the utility will search definitions of the word ‘entdeckung’ using its default server name and database. The default server name is read from the initialization file (see Initialization File). If it is not present, a predefined value specified at configuration time (see Default Server) is used. The default database is ‘!’, which means “search in all available databases until a match is found, and then display all matches in that database”.
There are two ways to change these defaults. First, you can use command line options. Secondly, you can use a DICT URL. Which method to use depends on your preferences. Both methods provide the same functionality for querying word definitions. However, command line options allow the user to query additional data from the server, which is impossible using URLs.
7.1.1 Dico Command Line Options
To connect to a particular dictionary server, use the --host option, for example:
$ dico --host dico.org entdeckung
To search in a particular database, use the --database (-d) option. For example, to display definitions from all databases:
$ dico --database '*' entdeckung
Note single quotes around the asterisk.
To get a list of databases offered by the server, use the --dbs (-D) option. In this case you may not give any non-option arguments. For example:
$ dico --dbs
If you wish to get a list of matches, instead of definitions, use the --match (-m) option. For example, the following invocation will display all matches from all the databases:
$ dico --database '*' --match entdeckung
The match mode uses ‘.’ strategy by default (see strategy), which means a server-dependent default strategy, which suits best for interactive spell checking. To select another strategy, use the --strategy (-s) option.
If the remote server supports ‘xlev’ experimental capability (see XLEV, you may use the --levdist (--levenshtein-distance) option to set maximum Levenshtein distance, for example:
$ dico --levdist 2 --match entdeckung
Note that setting the distance too high is impractical and may imply unnecessary strain on the server.
To get a list of available matching strategies, with descriptions, use the --strategies (-S) option.
7.1.2 DICT URL
Another way to specify data for a query is by using URL, instead of a word to search, as in the example below:
$ dico dict://gnu.org.ua/d:entdeckung
A DICT URL consists of the following parts:
The ‘/d’ syntax requests the definition of word, whereas the ‘/m’ syntax queries for matches, and is similar to the --match option. Some or all of ‘user;pass@’, ‘:port’, database, strat, and and n may be omitted. The meaning of all URL parts and their default values (if appropriate) are explained in the table below:
The user name to use in authentication. Similar to the --user option. If user is omitted and cannot be retrieved by other means, no authentication is attempted. See Autologin, for a detailed description of authentication procedure and sources which are used to obtain authentication credentials.
A shared key (password) for that user. This part is similar to the --key command line option.
For compatibility with other URLs,
dicotolerates a colon (instead of semicolon) as a delimiter between user and pass.
If user is given, but pass is not,
dicowill ask you to supply a password interactively (see Autologin).
Host name, IPv4 address, or IPv6 address (in square brackets) of the server to query. Same as the --host command line option.
Port number or service name (from /etc/services). If it is not present, the default of 2628 is used.
Same as the --port command line option.
The word to look for.
The database to search in. If not given, ‘!’ is assumed.
Same as the --database command line option.
The matching strategy to use. If omitted, ‘.’ is assumed.
Same as the --strategy command line option.
Extract and display the nth definition of the word. If omitted, all definitions are displayed.
There is no command line option equivalent for this parameter, because it is used rarely.
Trailing colons may be omitted. For example, the following URLs might specify definitions or matches:
dict://dict.org/d:shortcake: dict://dict.org/d:shortcake:* dict://dict.org/d:shortcake:wordnet: dict://dict.org/d:shortcake:wordnet:1 dict://dict.org/d:abcdefgh dict://dict.org/d:sun dict://dict.org/d:sun::1 dict://dict.org/m:sun dict://dict.org/m:sun::soundex dict://dict.org/m:sun:wordnet::1 dict://dict.org/m:sun::soundex:1 dict://dict.org/m:sun:::
7.2 Interactive Mode
If neither word nor URL nor any operation mode option were
given on the command line,
dico enters interactive mode. In
this mode it reads commands from the standard input, executes them and
displays results on the standard output. If the standard input is
connected to a terminal, the readline and history facilities are
enabled (see Command Line Editing in GNU Readline Library).
When in interactive mode,
dico displays its prompt and
waits for you to enter a command. The default prompt is the name
of the program, followed by a ‘greater than’ sign and a single
The input syntax is designed so as to save you the maximum amount of typing.
If you type any word, the default action is to look up its definition using the default server and database settings, for example:
dico> man From eng-swa, English-Swahili xFried/FreeDict Dictionary: man <n.> mwanamume
To match the word, instead of defining it, prefix it with a slash,
much as you do in
dico> /man From eng-swa, English-Swahili xFried/FreeDict Dictionary: 0) ``can'' 1) ``man'' 2) ``many'' 3) ``map'' 4) ``may'' 5) ``men''
Displayed is a list of matches retrieved using the default strategy. To see a definition for a particular match, type the number shown at its left. For example, to define “men”:
dico> 5 From eng-swa, English-Swahili xFried/FreeDict Dictionary: men <n.> wanaume
Define and match are two basic actions. To discern from them, the
dico commands begin with a command prefix, a
single punctuation character selected for this purpose. The default
command prefix is a dot, but it can be changed using the
command (see prefix).
We will discuss the
dico commands in the following
7.2.1 Server Commands
open command establishes connection to a remote
server. It takes up to two arguments, first of them specifying
the IP or host name of the server, and the optional second one
specifying the port number to connect to. For example:
dico> .open gnu.org.ua
If any or both of its arguments are absent, the
reuses the value supplied with its previous invocation, or, if it is
issued for the first time, the default values. The default for server
name is ‘gnu.org.ua’ and the default port number is 2628. Both
values can be changed at configuration time, see Default Server
for a detailed instruction.
When given one argument,
open checks if it begins with a
directory separator (‘/’). If so, the argument is handled as the
full file name of a UNIX socket.
Note that you are not required to issue this command. If it is not
dico will attempt to establish a connection using its
default settings before executing any command that requires a
connection to the server.
close command closes the connection. It does not take
7.2.2 Database and Strategy
database command changes or displays the database name which
is used by define and match commands. To display the database name,
type the command without arguments:
dico> .database !
To change the database, give its name as an argument to the command:
dico> .database *
Once the connection with the server is established, you may use command line completion facility to select the database from among those offered by the server. Typing TAB will show you a list of databases that begin with the characters you typed:
dico> .database enTAB en-pl-naut eng-afr eng-deu eng-swa
If you supply enough characters to identify a single choice, TAB will automatically select it. In the example above, typing a TAB after
dico> .database en-
completes the database name to:
dico> .database en-pl-naut
strategy command displays or changes the default strategy
name. As with
database, the strategy completion is available
for this command.
dico> .strategy . dico> .strategy dlev
If the remote server supports ‘xlev’ experimental capability
(see XLEV), you can use the
to set the maximum Levenshtein distance for strategies that use
Levenshtein algorithm. If used without arguments, this command
displays the distance reported by the server and the configured
dico> .distance Reported Levenshtein distance: 1 No distance configured
If used with a single numeric argument, it attempts to set the distance to the supplied value.
7.2.3 Informational Commands
ls command lists available strategies (see SHOW
dico> .ls exact "Match words exactly" prefix "Match word prefixes" soundex "Match using SOUNDEX algorithm" all "Match everything (experimental)" lev "Match headwords within given Levenshtein distance" dlev "Match headwords within given Damerau-Levenshtein distance" re "POSIX 1003.2 (modern) regular expressions" regexp "Old (basic) regular expressions" suffix "Match word suffixes" rev-qu "Reverse search in Quechua databases"
ld command lists available databases (see SHOW
dico> .ld eng-swa "English-Swahili xFried/FreeDict Dictionary" swa-eng "Swahili-English xFried/FreeDict Dictionary" afr-eng "Afrikaans-English FreeDict Dictionary" eng-afr "English-Afrikaans FreeDict Dictionary"
info command displays information about a database, whose
name is given as its argument. If used without arguments, it displays
information about the current database.
dico> .info pl-en-naut pl-en-naut - A Polish-English dictionary of nautical terms. Copyright (C) 2008 Sergey Poznyakoff Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover and Back-Cover Texts.
7.2.4 History Commands
Each issued command is stored in a history list and assigned a
unique event number. When
dico exits, it saves the
command history to a file named .dico_history in your home
directory. Upon startup, it retrieves the history from this file, so
the history is preserved between sessions.
You can view the command history using the
dico> .history 1) .open dict.org 2) entdeckung 3) /geschwindigkeit
A number of editing commands is provided, that allow you to refer to
previous events from the history list and to edit them. For example,
to re-issue the 3rd event from the above list, type ‘!3’. The
command with this index will be inserted at the
and you will be given a possibility to edit it. For a detailed
description of all history-editing commands, please refer to
Using History Interactively in GNU History User Manual.
When a command produces output that contains more lines than
there are rows on the terminal,
dico attempts to use a
pager program to display it. The name (and arguments) of
the pager program are taken from the
dico internal variable,
or, if it is not set, from the
PAGER environment variable.
dico pager setting can be examined or changed using
pager command. When used without arguments, it displays
the current setting:
dico> .pager less (Pager set from environment)
When used with a single argument, it sets the pager:
dico> .pager "less -R"
The argument ‘-’ (a dash) disables pager.
7.2.6 Program Settings
The commands described in this subsection are designed mostly for
dico initialization file (see Initialization File).
autologin command sets the name of autologin file to
be used for authentication. When used without arguments, it displays
the current setting. The argument to
autologin command is
subject to tilde expansion, i.e. if it begins with ‘~/’,
this prefix is replaced with the name of the current user home
directory, followed by ‘/’. Similarly, a prefix
‘~login/’ is replaced by the home directory for user
login, followed by a slash.
See Autologin, for a detailed discussion of the autologin feature.
quiet command toggles the display of
startup banner. When started,
dico prints a short list
of information useful for beginning users: the program version and
warranty conditions and a command to get help, e.g.:
dico 2.7 Copyright (C) 2005-2016 Sergey Poznyakoff License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type ? for help summary dico>
If you find this output superfluous and useless, you can suppress it by setting
in your initialization file.
7.2.7 Session Transcript
Session transcript is a special mode, which displays raw DICT commands and answers as they are executed. It is useful for debugging purposes.
You enable session transcript by issuing the following command:
dico> .transcript yes # or dico> .transcript on
Starting from then, each DICT transaction will be displayed on standard error output, for example:
dico> .open dico: Debug: S:220 Pirx.gnu.org.ua dicod (dico 2.7) <mime.xversion.xlev> <firstname.lastname@example.org> dico: Debug: C:CLIENT "dico 1.99.91" dico: Debug: S:250 ok dico: Debug: C:SHOW DATABASES dico: Debug: S:110 26 databases present … dico: Debug: S:. dico: Debug: S:250 ok dico: Debug: C:SHOW STRATEGIES dico: Debug: S:111 10 strategies present: list follows dico: Debug: S:exact "Match words exactly" dico: Debug: S:prefix "Match word prefixes" dico: Debug: S:soundex "Match using SOUNDEX algorithm" … dico: Debug: S:. dico: Debug: S:250 ok
In the example above, ellipses are used to replace long lists of data. As you see, session transcripts may produce large amount of output.
To turn the session transcript off, use the following command:
dico> .transcript no # or dico> .transcript off
Finally, to query the current state of session transcript, issue this command without arguments:
dico> .transcript transcript is on
7.2.8 Other Commands
prefix command queries or changes the current command prefix:
dico> .prefix Command prefix is . dico> .prefix @ dico> @prefix Command prefix is @
prompt command changes the
dico command line
prompt. For example, to change it to ‘dico$’, followed by a single
dico> .prompt "dico$ " dico$ _
Note the use of quotes to include the space character in the argument.
help command displays a short command usage summary. For
convenience, a single question mark can be used instead of it:
dico> ? /WORD Match WORD. / Redisplay previous matches. NUMBER Define NUMBERth match. !NUMBER Edit NUMBERth previous command. .open [HOST [PORT]] Connect to a DICT server. .close Close the connection. …
version command displays the package name and version
number, and the
warranty command displays the copyright
quit command leaves the dico shell. Typing
end-of-file character (C-d) has the same effect.
7.2.9 Dico Command Summary
For convenience, this subsection lists all available
commands along with their short description and a reference to the
part of this manual where they are described in detail. The command
names are given without prefix.
open host port
Connect to a DICT server. Both arguments are optional. If any of them is absent, the value supplied with the previous
opencommand is used. If there was no previous value, the default is used, i.e., ‘gnu.org.ua’ for host, and 2628 for port.
Close the connection.
Set or display the autologin file name.
Without argument, show whether the SASL authentication is enabled. With argument, enable or disable it, depending on the value of bool. See Autologin.
Set or display the current database name.
Set or display the current strategy name.
Set or query Levenshtein distance. This command takes effect only if the remote server supports ‘xlev’ experimental capability (see XLEV).
List available matching strategies.
List all accessible databases.
Display information about the database db, or the current database, if used without argument.
Set or display the command prefix.
Set or display session transcript mode.
See Session Transcript.
Set or display debugging verbosity level. Currently (as of version 2.7) it is a no-op.
Change command line prompt.
Change or display pager settings.
Display command history.
See History Commands.
Display short command usage summary.
Print program version.
Print copyright statement.
Toggle display of
dicowelcome banner. This command can be used only in initialization file.
Quit the shell.
7.3 Initialization File
When you start
dico, it automatically executes commands from its
initialization files (or init files, for short), normally
called .dico. Two init files are read: the one
located in your home directory, and the one from the current working
directory. It is not an error if any or both of these files are absent.
These files contain a series of
dico commands, as
described in Interactive Mode, with the only difference that
no command prefix is used by default. The ‘#’ character
introduces a comment: any characters from (and including) ‘#’ up
to the newline character are ignored4.
Init files are useful to change the defaults for your
invocation. Consider, for example, this init file:
# An example init file for
dico# Turn the welcome banner off quiet yes # Set the location of autologin file autologin ~/.dicologin # Use this server by default open dict.org # Search in all databases database * # Finally, set the custom command prefix prefix :
Notice, that if you wish to change your command prefix, it is preferable to do it as a last command in your init file, as shown in this example.
After connecting to a remote server,
dico checks if
the server supports authentication and attempts to authenticate itself
if so. To do this
dico needs a set of parameters called
user credentials. The exact set of credentials depends on the
authentication mechanism being used, with user name and password being
the two most important ones.
The user credentials can be supplied from the following sources:
- Command line options --user and --password.
- An URL given as a command line argument (see user).
- Autologin files.
These three sources are consulted in that order, i.e., a user name supplied with the --user command line option takes precedence over the one found in an URL and over any names supplied by autologin files.
If, after consulting all these sources, the user name is
established, while the password is not, the resulting action
depends on whether the standard input is connected to a terminal.
If it is,
dico will ask the user to supply a password.
If it is not, authentication is aborted and connection to the server
Some authentication mechanisms require additional credentials. For example, GSSAPI authentication requires a service name. These credentials can be supplied only in autologin file.
Autologin file is a plaintext file that contains
authentication information for various DICT servers. At
most two autologin files are consulted: first the session-specific
file, if it is supplied by
autologin command (see autologin) or by the --autologin command line
option, next the default file .dicologin in the user’s home
directory. The default autologin file is examined only if
no matching record was found in the session-specific one.
The autologin file format is similar to that of .netrc file
Comments are introduced by a pound sign. Anything starting from ‘#’ up to the end of physical line is ignored.
Empty lines and comments are ignored.
Non-empty lines constitute statements. Tokens in a statement are separated with spaces, tabs, or newlines. A valid statement must begin with one of the following:
This statement contains parameters for authenticating on machine name.
This statement contains parameters for authenticating on any machine, except those explicitly listed in
machinestatements. There can be at most one
defaultstatement in autologin file. Its exact location does not matter, it will always be matched after all explicit
During the lookup,
dico searches the autologin file for a
machine statement whose name matches the remote server
name as given by --host command line option, host part of an
URL (see urls), or the argument to the
command (see open). If it reaches end of the
file without having found such an entry, it uses the
value, if available.
Once a matching entry is found, its subsequent tokens are analyzed. The following tokens are recognized:
Supply user name for this server.
Supply a password.
Do not perform authentication on this machine.
Enable SASL authentication.
Disable SASL authentication.
Declare acceptable SASL mechanisms. The list argument is a comma-separated list of mechanism names, without intervening whitespace. Multiple
mechanismsmay be given, in which case the corresponding lists are concatenated.
Declare service name, for authentication methods that need it. If this token is omitted, the default service name ‘dico’ is used.
Declare realm for authentication.
Set host name for this machine. By default, it is determined automatically.
Consider the following autologin entry, for example:
machine a.net user smith password guessme machine b.net sasl mechanisms gssapi,digest-md5 realm example.net service dico user smith password guessme default noauth
When connecting to the server ‘a.net’,
dico will attempt
the usual APOP authentication as user ‘smith’ with password
‘guessme’. When connecting to the machine ‘b.net’, it will
use SASL authentication, via either GSSAPI or
DIGEST-MD5 mechanisms, with realm name ‘example.net’,
service name ‘dico’ and the same user name and password, as for
The authentication mechanism is suppressed if the
option has been given in the command line, or a matching entry was
found in one of the autologin files, which contained the
7.5 Dico invocation
This section contains a short summary of
dico command line
The following table summarizes the four existing ways of
dico [options] word
Connect to the dictionary and define or match a word.
See dico options.
dico [options] url
Connect to the dictionary and define or match a word, supplied in the url.
dico [options] opmode
Connect to the dictionary and query the information required by opmode option, which is one of --dbs, --strategies, --serverhelp, --info, or --serverinfo. See below (see Operation modes) for a description.
Start interactive shell. See Interactive Mode.
Server selection options:
Connect to this server.
- -p port
Specify the port to connect to. The argument port can be either a port number or its symbolic service name, as listed in /etc/services.
- -d name
Select a database to search. The name can be either a name of one of the databases offered by the server (as returned by --dbs option), or one of the predefined database names: ‘!’ or ‘*’.
Set source address for TCP connections.
Match instead of define.
- -s name
Select a strategy for matching. The argument is either a name of one of the matching strategies supported by server (as displayed by --strategies option) or a dot (‘.’) meaning a server-dependent default strategy.
This option implies --match.
Sets maximum Levenshtein distance. Allowed values of n are between 1 and 9 inclusively. This option has effect only if the remote server supports ‘xlev’ extension (see XLEV).
Do not print the normal
dicowelcome banner when entering interactive shell.
Show available databases.
Show available search strategies.
Show server help.
- -i dbname
Show information about database dbname.
Show information about the server.
Enable SASL authentication, if the server supports it. See Autologin.
Disable SASL authentication. See Autologin.
- -u name
Set user name for authentication.
- -k string
Set shared secret for authentication.
Set the name of autologin file to use.
- -c string
Additional text for client command, instead of the default ‘GNU dico 2.7’.
Enable session transcript. See Session Transcript, for a description.
Increase debugging verbosity level.
Include time stamp in the debugging output.
Include source line information in the debugging output.
Display a short description of command line options.
Display a short usage message
Print program version.
The same holds true for interactive mode as well, but you will hardly need comments on a terminal.
This document was generated on September 25, 2018 using makeinfo.Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.