NAME

       ident_lookup,  ident_id,  ident_free,  id_open,  id_close, id_query, id_parse, id_fileno -
       query remote IDENT server

SYNOPSIS

       #include <ident.h>

       High-level calls

       IDENT *ident_lookup(int fd, int timeout)

       char *ident_id(int fd, int timeout)

       void ident_free(IDENT *id)

       Low-level calls

       id_t *id_open(laddr, faddr, timeout)
       struct in_addr *laddr, *faddr;
       struct timeval *timeout;

       int id_close(id)
       id_t *id;

       id_query(id, lport, fport, timeout)
       id_t *id;
       int lport, fport;
       struct timeval *timeout;

       int id_parse(id, timeout, lport, fport, identifier,
            opsys, charset)
       id_t *id;
       struct timeval *timeout;
       int *lport, *fport;
       char **identifier, **opsys, **charset;

       int id_fileno(id)
       id_t *id;

DESCRIPTION

       ident_lookup tries to connect to a remote IDENT server to establish the  identity  of  the
       peer  connected  on  fd, which should be a socket file descriptor.  timeout is the longest
       permissible time to block waiting for an answer, and is given in seconds.  A  value  of  0
       (zero)  means wait indefinitely (which in the most extreme case will normally be until the
       underlying network times out).  ident_lookup returns a pointer to an IDENT  struct,  which
       has the following contents:

              typedef struct {
                   int lport;          /* Local port */
                   int fport;          /* Far (remote) port */
                   char *identifier;   /* Normally user name */
                   char *opsys;        /* OS */
                   char *charset;      /* Charset (what did you expect?) */
              } IDENT;

       For a full description of the different fields, refer to RFC-1413.

       All  data  returned  by ident_lookup (including the IDENT struct) points to malloc'd data,
       which can be freed with a call to ident_free.  ident_lookup returns 0 on error or timeout.
       Presently,  this  should  normally be taken to mean that the remote site is not running an
       IDENT server, but it might naturally be caused by other network related problems as  well.
       Note that all fields of the IDENT struct need not necessarily be set.

       ident_id  takes  the  same  parameters  as  ident_lookup  but  only returns a pointer to a
       malloc'd area containing the identifier string, which is probably  the  most  wanted  data
       from the IDENT query.

       ident_free  frees  all  data  areas  associated  with  the  IDENT struct pointed to by id,
       including the struct itself.

                                            Low-level calls

       The low-level calls can be used when greater flexibility is needed. For example,  if  non-
       blocking I/O is needed, or multiple queries to the same host are to be made.

       id_open  opens  a connection to the remote IDENT server referred to by faddr.  The timeout
       is specified by timeout.  A null-pointer means wait indefinitely, while  a  pointer  to  a
       zero-valued  timeval  struct  sets  non-blocking  I/O,  in  the same way as for select(2).
       id_open returns a pointer to an id_t datum, which is an opaque structure  to  be  used  as
       future reference to the opened connection. When using non-blocking I/O it might however be
       useful to access the underlying socket file descriptior, which can be  gotten  at  through
       the id_fileno macro described below.

       id_close closes the connection opened with id_open and frees all data associated with id.

       id_query  sends  off  a  query  to a remote IDENT server.  lport and fport are sent to the
       server to identify the connection for which identification is needed.  timeout is given as
       for  id_open.   If  successful,  id_query  returns  the number of bytes sent to the remote
       server. If not, -1 is returned and errno is set.

       id_parse parses the reply to a query sent off by id_query and returns information  to  the
       locations  pointed  to  by  lport,  fport, identifier, opsys and charset.  For string data
       (identifier, opsys and charset) pointers to malloc'd space are returned.

       id_parse returns:

               1     If completely successful.

              -3     Illegal reply type from remote server.  identifier is  set  to  the  illegal
                     reply.

              -2     Cannot  parse  the reply from the server.  identifier is normally set to the
                     illegal reply.

              -1     On general errors or timeout.

               0     When non-blocking mode is set and id_parse  has  not  finished  parsing  the
                     reply from the remote server.

               2     Indicates the query/reply were successful, but the remote server experienced
                     some error.  identifier is set to the error message from the remote server.

       For all errors, errno is set as appropriate.

       id_fileno is a macro that takes  an  id_t  handle  and  returns  the  actual  socket  file
       descriptor used for the connection to the remote server.

ERRORS

       ETIMEDOUT      The call timed out and non-blocking I/O was not set.

EXAMPLES

       Here's  an  example  how to handle the reply from id_reply() in the case that non-blocking
       I/O is set. Note that id_reply() will return 0 as long as  it's  not  finished  parsing  a
       reply.

              int rcode;

               ...

              idp = id_open(...)

               ...

              while ((rcode = id_parse(idp, timeout,
                              &lport, &fport, &id, &op, &cs)) == 0)
                   ;

              if (rcode < 0)
              {
                if (errno == ETIMEDOUT)
                  foo();     /* Lookup timed out */
                else
                  bar();      /* Fatal error */
              }
              else if (rcode == 1)
              {
                /* Valid USERID protocol reply */
              }
              else if (rcode == 2)
              {
                /* Protocol ERROR reply */
              }

SEE ALSO

       RFC-1413, socket(2), select(2)

AUTHORS

       Peter Eriksson <pen@lysator.liu.se>
       Par Emanuelsson <pell@lysator.liu.se>

BUGS

       For ident_lookup and ident_id the blocking time in extreme cases might be as much as three
       times the value given in the timeout parameter.