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

FreeBSD Manual Pages

  
 
  

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

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 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.

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>
       Remi 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.

Lysator	ACS			11 August 2003			      IDENT(3)

NAME | SYNOPSIS | DESCRIPTION | ERRORS | EXAMPLES | SEE ALSO | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ident&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help