Man Linux: Main Page and Category List

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.