![[image of the Head of a GNU]](/graphics/gnu-head-sm.jpg)
|
|
Dico |
GNU Dictionary Server |
Sergey Poznyakoff |
| GNU Dico Manual (split by chapter): |  |
 |
 |
 |
 |
 |
 |
? |
This appendix describes commands understood by Dico dictionary server. Provided examples follow the convention used in RFC documents: a text sent by the server is prefixed with ‘S’, whereas a text sent by the client is prefixed with ‘C’.
When connection is established, the server sends an initial reply to the client. This reply has the following format:
220 hostname text <capabilities> msg-id |
Its parts and their meaning are described in the following table:
The name of the host. It is determined automatically, unless set
using hostname configuration file statement (see hostname directive).
Arbitrary text, as set via initial-banner-text configuration
statement (see section initial-banner-text).
A comma-separated list of server capabilities. It is configured using
capability statement (see section Server Capabilities).
A unique identifier similar to the format specified in RFC822, except that spaces and quoted pairs are not allowed within it.
This identifier will be used by the client when formulating the
authentication string used in the AUTH command (see section The AUTH Command).
An example of initial reply follows:
220 Trurl.gnu.org.ua <auth.mime> <520.1212912026@Trurl.gnu.org.ua> |
The following are standard commands, defined in RFC2229.
The DEFINE command searches for definitions of a word.
Look up the word word in database db. If db is
‘!’, then all the databases will be searched until the word is
found, and all matches in that database will be returned. Similarly,
if db is ‘*’, then all the databases will be searched and
all matches in all databases will be returned. In these two cases,
the databases are searched in the same order as that returned by
SHOW DB command (see section SHOW DB).
If the word was not found, response code 552 is returned.
If the word is found, a response code 150 is sent, followed by the
number of definitions found. Then, for each definition a response
code 151 is returned, followed by the textual body of the definition.
In a 151 response, the first three space-delimited parameters give the
word looked for, the name and a short description of the database.
The latter two are the same as shown in the output from SHOW DB
command.
The textual body of each definition is terminated with a dot (‘.’) on a line alone. If any line in the definition begins with a dot, it is duplicated to avoid confusion with body terminator.
After all of the definitions have been sent, a status code 250 is
sent. If timing is set to ‘true’ in the configuration
file, this latter response also carries timing information.
See section Tuning, for more information about timing output.
Possible responses from DEFINE command are:
Example transaction:
C: DEFINE eng-swa man S: 150 1 definitions found: list follows S: 151 "man" eng-swa "English-Swahili xFried/FreeDict Dictionary" S: man <n.> S: S: mwanamume S: S: . S: 250 Command complete [d/m/c = 1/0/12 0.000r 0.000u 0.000s] |
The MATCH command searches for word in the database index.
The searching algorithm is called strategy. The following
strategies are supported by the server:
Match a word exactly (case-insensitive).
Match a word prefix (case-insensitive).
Match using SOUNDEX algorithm.
Match headwords within given Levenshtein distance. That distance,
called a Levenshtein threshold is by default 1. It can be
modified using the XLEV extension command (see section XLEV).
Match headwords within given Damerau-Levenshtein distance. That distance is the same as for the ‘lev’ strategy.
Match using POSIX 1003.2 (a.k.a ‘extended’) regular expressions.
Match using basic regular expressions.
The dictorg module (see section The dictorg module.) additionally provides the
following strategy:
Match word suffixes (case-insensitive).
Other modules may provide more matching strategies.
Match word in database using strategy. As with
DEFINE, the database can be ‘!’ or ‘*’
(See section The DEFINE Command, for a detailed description of these wildcards).
The strategy is either the name of a strategy to use, or
a dot (‘.’), meaning to use default strategy. The default
strategy is set using default-strategy configuration file
statement (see section default-strategy. Its default
value is ‘lev’, which means ‘use Levenshtein algorithm’ (see
above).
If no matches are found in any of the searched databases, then response code 552 will be returned. Otherwise, response code 152 will be returned followed by a list of matched words, one per line, in the form:
database word |
Thus, prepending a ‘DEFINE ’ to each such response, one obtains a
valid DEFINE command.
The textual body of the match list is terminated with a line containing only a dot character.
Following the list, response code 250 is sent, which includes
timing information, if timing directive is set in the
configuration file (see section Tuning).
Possible responses:
Examples:
C: MATCH * . "weather" S: 152 12 matches found: list follows C: eng-afr "feather" C: eng-afr "leather" C: eng-afr "weather" C: eng-deu "feather" C: eng-deu "heather" C: eng-deu "leather" C: eng-deu "weather" C: eng-deu "wether" C: eng-deu "wheather" C: devils "WEATHER" S: . S: 250 Command complete [d/m/c = 0/12/100677 0.489r 0.479u 0.007s] |
The SHOW command outputs various information about the server
and databases.
Display the list of currently accessible databases, one per line, in the form:
database description |
The list is terminated with is a dot (‘.’) on a line alone.
Possible responses:
Display the list of currently supported search strategies, one per line, in the form:
strategy description |
The list is terminated with is a dot (‘.’) on a line alone.
Possible responses:
Displays the information about the specified database. The information is a free-form text and is suitable for display to the user in the same manner as a definition. The textual body of the response is terminated with is a dot (‘.’) on a line alone.
Possible responses:
The textual body is retrieved from the info statement in the
configuration file (see section info), or, if it is not
specified, from the database itself, using dico_db_info
callback function (see dico_db_info). If neither source
returns anything, the string ‘No information available.’ is returned.
Return a server-specific information.
Response:
The information follows, terminated with a dot on a line alone.
The textual body returned by the SHOW SERVER command consists
of two parts. It begins with a line containing host name of the
server and, optionally an additional information about the daemon and
the system it runs on. The exact look and amount of information in
this line is controlled by show-sys-info configuration
statement (see section show-sys-info). This line is
followed by the text supplied with server-info configuration
statement (see section server-info).
The OPTION command allows to request optional features
on the remote server. Currently the only implemented subcommand is:
Requests that all text responses be prefaced by a MIME header (RFC2045) followed by a single blank line.
After this command is issued, the server begins each textual response with a MIME header. This header consists of ‘Content-type’ and ‘Content-transfer-encoding’ headers, as supplied by the corresponding configuration file statements for this database (See section content-type, see section content-transfer-encoding). Any or both of these headers may be missing.
The AUTH command allows client to authenticate itself to the
server. Depending on the server configuration, authenticated users
may get access to more databases (see section Database Visibility) or more
detailed server information (see section show-sys-info).
Authenticate client to the server using a username and password. The auth-string is computed as in the APOP protocol (RFC1939. Briefly, it is the MD5 checksum of the concatenation of the msg-id (see section Initial Reply) and the shared secret that is stored both on the server and client machines.
See section Authentication, for information on how to configure server for authenticating clients.
This command is supported only if ‘auth’ capability is requested in the configuration (see section auth).
Identify client to server. The info argument contains a string identifying the client program (e.g. its name and version number). This information can then be used in logging (see section %C).
Display cumulative timing information. This command returns a ‘210’ status code, followed by the timing information as described in Tuning, e.g.
C: STATUS S: 210 [d/m/c = 28/1045/119856 21.180r 10.360u 1.040s] |
The HELP command provides a short summary of commands that
are understood by the server. The response begins with a ‘113’
code, followed by textual body defined in help-text
configuration file statement (see section help-text),
which is terminated by a dot on a line by itself. A ‘250’
response code finishes the output. For example:
113 help text follows DEFINE database word -- look up word in database MATCH database strategy word -- match word in database SHOW DB -- list all accessible databases SHOW DATABASES -- list all accessible databases SHOW STRAT -- list available matching strategies SHOW STRATEGIES -- list available matching strategies SHOW INFO database -- provide database information SHOW SERVER -- provide site-specific information CLIENT info -- identify client to server STATUS -- display timing information HELP -- display this help information QUIT -- terminate connection . 250 Ok |
Terminate connection.
This command returns a response code 221, optionally followed by timing information (see section Tuning).
In addition to the standard commands, the Dico server also offers a set of experimental or extended commands.
This command displays the current inactivity timeout setting (see inactivity-timeout), and resets idle timer to 0. The timeout value is printed as the first word after a ‘110’ reply code, e.g.:
C: XIDLE S: 110 180 second(s) |
The value of ‘0’ means there are no timeout.
This command displays the daemon implementation and version number. It becomes available only if ‘xversion’ capability was requested in the configuration file (see section xversion).
C: XVERSION S: 110 dicod (dico 2.1) |
If param is the word ‘tell’, displays the current value of Levenshtein threshold. If param is a positive integer value, sets the Levenshtein threshold to this value.
This command becomes available only if ‘xlev’ capability was requested in the configuration file (see section xlev).
C: xlev tell S: 280 1 C: xlev 3 S: 250 ok - Levenshtein threshold set to 3 C: xlev tell S: 280 3 |
|
|
 |
|
|
? |
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.