LIBDICT(3)

NAME
LIBDICT - A C library for interacting with RFC2229 dictionary servers. This manpage is for version 0.9.

SYNOPSIS
#include <libdict.h>

extern int ld_errno;

struct ld_conn *ld_newconn(host, port, timeout, client, debug);
char *host;
int port;
int timeout;
ld_bool debug;

void ld_freeconn(conn);
struct ld_conn *conn;

void ld_closeconn(conn);
struct ld_conn *conn;

ld_bool ld_auth(conn, user, pw);
struct ld_conn *conn;
char *user;
char *pw;

char *ld_serverinfo(conn);
struct ld_conn *conn;

char *ld_getsrvreply(conn);
struct ld_conn *conn;

struct ld_dbs **ld_getdbs(conn);
struct ld_conn *conn;

struct ld_dbs **ld_getstrats(conn);
struct ld_conn *conn;

ld_bool ld_setstrat(conn, strat);
struct ld_conn *conn;
char *strat;

ld_bool ld_setdb(conn, db);
struct ld_conn *conn;
char *db;

struct ld_defanswer **ld_define(conn, word);
struct ld_conn *conn;
char *word;

struct ld_matchanswer **ld_match(conn, word);
struct ld_conn *conn;
char *word;

enum ld_servcode ld_getrespno(msg);
char *msg;

ld_bool ld_checkok(respno);
int respno;

int ld_geterrno(conn);
struct ld_conn *conn;

char *ld_strerror(lderrno);
int lderrno;

DESCRIPTION
libdict is a small C library that provides access to RFC2229 dictionary servers. This is done through a series of functions, each representing a major function of the dict server. The first step to using a dict server is to establish a connection to the dict server. The function used to do this is:
  struct ld_conn *dictconn;
  dictconn = ld_newconn(host, port, timeout, client, debug); host is the hostname of the dict server to be connected to. This option is required. port is the port on host to connect to. If this is set to 0, libdict will try to look up the correct port in /etc/services. If this fails it will simply default to 2628. timeout specifies how long libdict will wait for the server to respond to requests before returning an error. A value of 0 means no timeout. client is an optional field which specifies how libdict will introduce itself to the server using the CLIENT command. NULL means it will default to a generic libdict greeting. debug is a boolean value that enables socket-level debugging of the server connection. If this is set to LD_True, libdict will display to stdout all communications between the client and the server. After you call this command you should call ld_geterrno() and ensure it returns LDOK. Otherwise an error occurred during the connection and you should use ld_strerror to find out the exact cause. ld_getsrvreply can be used after any libdict function is used which interacts with the server and completes successfully, in which case it should return the server's text response. This can be used with ld_getrespno to determine with a greater degree of precision exactly what the server's response was. A 'sister' function to ld_getsrvreply is:
  char *info;
  info = ld_getserverinfo(dictconn); dictconn is the connection handle returned by a previous call to ld_newconn. This function will always return the server banner for the specified connection. After a connection has been established, it may be necessary to authenticate with the server in order to gain access to private dictionaries. The function used to authenticate is:
  ld_bool success;
  success = ld_auth(dictconn, user, pw); dictconn is the connection handle returned by a previous call to ld_newconn. user is the username to use for authentication. pw is the secret to use for authentication. Note that libdict does not perform any hashing of pw on it's own - if the password must be hashed then it must be done before the call to ld_auth. After the connection is established, most applications will want to retrieve a list of dictionaries and matching strategies available to them. This is done using the following functions:
  struct ld_dbs **dicts, **strats;
  dicts = ld_getdbs(dictconn);
  strats = ld_getstrats(dictconn); ld_getdbs and ld_getstrats will return a list of all the databases available, or strategies available, respectively. They will be placed in an array of pointers to struct ld_dbs. struct ld_dbs is declares as follows:
  struct ld_dbs {
      char *ld_dbname;
      char *ld_dbdesc;
  }; where ld_dbname is the database/strategy name and ld_dbdesc is the database/strategy description. Here's a bit of example code to clarify the concept (note no error checking is performed in example code):
  struct ld_dbs **dicts;
  int x = 0;
  [ ... connection is established ... ]
  dicts = ld_getdbs(dictconn);
  while(dicts[x]) {
       printf("Dictionary: %sescription: %s,
           dicts[x]->ld_dbname, dicts[x]->ld_dbdesc);
    x++;
  } Once you have obtained a list of dictionaries/strategies, it may be necessary to indicate to the server which database you wish to search and which strategy you wish to use. The following functions are use to specify these:
  ld_bool ld_setdb(dictconn, db);
  ld_bool ld_setstrat(dictconn, strat); db is the dictionary you wish to search, for example, 'web1913' or calls. If these functions are not called, the dictionary will default to '*' and the matching strategy will default to 'exact'. These functions will return LD_False if the db/strategy you specified does not exist or is unavailable. To perform an actual word lookup, the function used is as follows:
  struct ld_defanswer **answers;
  answers = ld_define(dictconn, word); word is the word to be defined. This will perform the lookup and return the results in answers. Here is some example code to illustrate the concept:
  struct ld_defanswer **answers;
  int x = 0;
  [ ... connection is established ... ]
  answers = ld_define(dictconn, "hello");
  while(answers[x]) {
    printf("Word: %s\nDictionary: %s\nDefinition:\n\t%s\n",
           answers[x]->answord, answers[x]->ansdict,
           answers[x]->ansdef);
    x++;
  } The process to match the word using one of the search strategies is very similar. The function used in this case is:
  struct ld_matchanswer **answers;

  answers = ld_match(dictconn, word); word is the word to be searched for. Here is some example code:
  struct ld_defanswer **answers;
  int x = 0;
  [ ... connection is established ... ]
  answers = ld_match(dictconn, "hello");
  while(answers[x]) {
    printf("Word: %sictionary: %s,
           answers[x]->answord, answers[x]->ansdict);
    x++;
  } All of these functions will generally make available the server's response string when they succeed. In this event you should use ld_getsrvreply (see above) to get the server's reply. You can then use the following function to determine exactly what the server's status is if you are not content with the highly granular error reporting libdict provides:
  int respno;
  respno = ld_getrespno(servermsg); servermsg is a string containing the server's response. The most common use of this function would be as follows:
  respno = ld_getrespno(ld_getsrvreply(dictconn)); Where respno is a variable of type enum ld_servcode. This variable type is defined in ldservcodes.h. Each possible response message from the server is enumerated and can be easily tested against. Finally, when it is time to disconnect from the server, there are two functions that can be used:
  ld_bool closeok;

  closeok = ld_closeconn(dictconn);
  ld_freeconn(dictconn); ld_closeconn will close a connection but will not destroy the connection handle. This way you can use ld_getsrvreply to get the server's goodbye message for informational purposes. After a call to ld_closeconn, ld_freeconn should be called in order to free the memory resources allocated. If ld_freeconn is called on a connection where ld_closeconn has not been called first, it will automatically call ld_closeconn to ensure a graceful shutdown. Note however that you cannot use ld_getsrvreply in this case as dictconn pointer will no longer be valid.

ERROR REPORTING
libdict does not at present support very detailed error reporting. Any call above that returns a pointer will return NULL on failure; any call returning a ld_bool value will return False on failure. If this occurs, ld_geterrno should be called to see what the error condition is. The syntax for ld_geterrno is:
  int status;
  status = ld_geterrno(conn);
  if(status != LDOK) {
     ...
  } The following return values are possible:
  LDOK - No error.
  LDERRNO - A low-level error occured; consult with errno
  LDBADARG - An argument passed to the libdict function was invalid.
  LDNOMATCH - No matches were returned for the query.
  LDBADPROTO - Something unexpected was received from the server.
  LDTIMEOUT - Operation timed out. You can convert these error codes to text strings using the following library function:
  struct ld_conn *conn;
  char *msg;
  msg = ld_strerror(ld_geterrno(conn)); ld_strerror will return a pointer to a static text string that contains a human-readable error message. In the event of LDERRNO, ld_strerror will call strerror and return the text form of the errno error.

DEFINED SYMBOLS/TYPES
libdict defines a few symbols and types for convenience. These symbols are:
  LDVERSION - The libdict version, represented as a string.
  LDVERMAJ - The major portion of the version number as an int.
  LDVERMIN - The minor portion of the version number as an int. It also defines the following type:
  ld_bool - An enumerated type that can be set to LD_False, LD_True), or LD_Maybe. This is used throughout libdict to indicate success of an operation, etc. A function returning 'Maybe' means there was an intermittent failure and the operation should be tried again before giving up.

AUTHOR
by Steven Young <sdyoung@well.com> This software is released under the MIT/X11 license; please see the LICENSE file that should have been included in this distribution.