Unix/Linux Go Back    


BSD 2.11 - man page for ident (bsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


IDENT(3)										 IDENT(3)

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 mal-
       loc'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, includ-
       ing 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 descrip-
       tor 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.

Lysator ACS				   4 April 1993 				 IDENT(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:56 PM.