NAME

ident_lookup, ident_id, ident_free, id_open_addr, 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

ident_t *id_open_addr (const struct sockaddr *laddr,
const struct sockaddr *faddr, struct timeval *timeout)
ident_t *id_open(const struct in_addr *laddr,
const struct in_addr *faddr, struct timeval *timeout)

int id_close(ident_t *id)

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

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

int id_fileno(ident_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. You should free() the result manually.

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_addr and id_open both open 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_addr and id_open return a pointer to an id_t data, 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. While id_open only works with IPv4 32-bits addresses, id_open_addr expects complete sockaddr structures. At the moment, it supports sockaddr_in (AF_INET) and sockaddr_in6 (AF_INET6) structures. id_open_addr was first introduced in libident version 0.30.

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:

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;
id_t idp;
/* ... */
idp = id_open_addr(...);
if (idp == NULL)
{


  perror ("id_open_addr");


  /* ... */
}
/* ... */
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>
Rémi Denis-Courmont <rdenis (at) simphalempin (dot) com>

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.