IDENT(3N) Lysator ACS IDENT(3N)
4 April 1993
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
- 1 - Formatted: November 14, 2024
IDENT(3N) Lysator ACS IDENT(3N)
4 April 1993
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. 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 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
descriptor used for the connection to the remote server.
ERRORS
ETIMEDOUT The call timed out and non-blocking I/O was not set.
- 2 - Formatted: November 14, 2024
IDENT(3N) Lysator ACS IDENT(3N)
4 April 1993
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.
- 3 - Formatted: November 14, 2024
