2.11BSD/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>
_H_i_g_h-_l_e_v_e_l _c_a_l_l_s
IDENT *ident_lookup(int fd, int timeout)
char *ident_id(int fd, int timeout)
void ident_free(IDENT *id)
_L_o_w-_l_e_v_e_l _c_a_l_l_s
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 _f_d, which
should be a socket file descriptor. _t_i_m_e_o_u_t 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 _I_D_E_N_T 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
_R_F_C-_1_4_1_3.
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 _i_d_e_n_t_i_f_-
_i_e_r 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 _i_d, including the struct itself.
_L_o_w-_l_e_v_e_l _c_a_l_l_s
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 _f_a_d_d_r. The timeout is specified by _t_i_m_e_o_u_t. A
null-pointer means wait indefinitely, while a pointer to a
zero-valued _t_i_m_e_v_a_l 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 _i_d.
id_query sends off a query to a remote IDENT server. _l_p_o_r_t
and _f_p_o_r_t are sent to the server to identify the connection
for which identification is needed. _t_i_m_e_o_u_t 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
_l_p_o_r_t, _f_p_o_r_t, _i_d_e_n_t_i_f_i_e_r, _o_p_s_y_s and _c_h_a_r_s_e_t. For string data
(_i_d_e_n_t_i_f_i_e_r, _o_p_s_y_s and _c_h_a_r_s_e_t) pointers to malloc'd space
are returned.
id_parse returns:
1 If completely successful.
-3 Illegal reply type from remote server. _i_d_e_n_t_i_f_i_e_r
is set to the illegal reply.
-2 Cannot parse the reply from the server. _i_d_e_n_t_i_f_-
_i_e_r 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. _i_d_e_n_t_i_f_i_e_r
is set to the error message from the remote
server.
For all errors, _e_r_r_n_o 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 <_p_e_n@_l_y_s_a_t_o_r._l_i_u._s_e>
P"ar Emanuelsson <_p_e_l_l@_l_y_s_a_t_o_r._l_i_u._s_e>
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
_t_i_m_e_o_u_t parameter.
Printed 11/24/99 4 April 1993 4