Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
IDENT(3)		   Library Functions Manual		      IDENT(3)

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

       #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)

       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 de-
       scriptor.  timeout is the longest permissible time to block waiting for
       an  answer, and is given	in seconds. A value of 0 (zero)	means wait in-
       definitely (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 nor-
       mally  be  taken	 to  mean that the remote site is not running an IDENT
       server, but it might naturally be caused	by other network related prob-
       lems as well.  Note that	all fields of the IDENT	struct need not	neces-
       sarily 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 connec-
       tion. 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	struc-
       tures.  At the moment, it  supports  sockaddr_in	 (AF_INET)  and	 sock-
       addr_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 identifica-
       tion  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  fin-
		     ished 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.

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

       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 */
		  bar();      /* Fatal error */
	      else if (rcode ==	1)
		/* Valid USERID	protocol reply */
	      else if (rcode ==	2)
		/* Protocol ERROR reply	*/

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

       Peter Eriksson <>
       Par Emanuelsson <>
       Remi Denis-Courmont <rdenis (at)	simphalempin (dot) com>

       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.

Lysator	ACS			11 August 2003			      IDENT(3)


Want to link to this manual page? Use this URL:

home | help