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