# 2.11BSD#431 - /usr/man/cat3/ident.0

    IDENT(3)	    UNIX Programmer's Manual		 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 indefin-
         itely (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 con-
         tents:

    	  typedef struct {
    	       int lport;	   /* Local port */

    Printed 11/24/99	  4 April 1993				1

    IDENT(3)	    UNIX Programmer's Manual		 IDENT(3)

    	       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 identif-
         ier 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 mul-
         tiple 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 under-
         lying 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.

    Printed 11/24/99	  4 April 1993				2

    IDENT(3)	    UNIX Programmer's Manual		 IDENT(3)

         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.	identif-
    	       ier 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)
    	       ;

    Printed 11/24/99	  4 April 1993				3

    IDENT(3)	    UNIX Programmer's Manual		 IDENT(3)

    	  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>
         P"ar 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.

    Printed 11/24/99	  4 April 1993				4

Generated: 2016-12-26 | Generated by man2html V0.25 page hit count: 390 |