1IDENT(3) Library Functions Manual IDENT(3)
2
6 ident_lookup, ident_id, ident_free, id_open_addr, id_open, id_close,
7 id_query, id_parse, id_fileno - query remote IDENT server
8
10 #include <ident.h>
11 High-level calls
13 IDENT *ident_lookup(int fd, int timeout)
15 char *ident_id(int fd, int timeout)
17 void ident_free(IDENT *id)
19 Low-level calls
21 ident_t *id_open_addr (const struct sockaddr *laddr,
23 const struct sockaddr *faddr, struct timeval *timeout)
24 ident_t *id_open(const struct in_addr *laddr,
25 const struct in_addr *faddr, struct timeval *timeout)
26 int id_close(ident_t *id)
28 int id_query(ident_t *id, int lport, int fport,
30 struct timeval *timeout)
31 int id_parse(ident_t *id, struct timeval *timeout,
33 int *lport, int *fport,
34 char **identifier, char **opsys, char **charset)
35 int id_fileno(ident_t *id)
37
39 ident_lookup tries to connect to a remote IDENT server to establish the
40 identity of the peer connected on fd, which should be a socket file
41 descriptor. timeout is the longest permissible time to block waiting
42 for an answer, and is given in seconds. A value of 0 (zero) means wait
43 indefinitely (which in the most extreme case will normally be until the
44 underlying network times out). ident_lookup returns a pointer to an
45 IDENT struct, which has the following contents:
46 typedef struct {
48 int lport; /* Local port */
49 int fport; /* Far (remote) port */
50 char *identifier; /* Normally user name */
51 char *opsys; /* OS */
52 char *charset; /* Charset (what did you expect?) */
53 } IDENT;
54 For a full description of the different fields, refer to RFC-1413.
56 All data returned by ident_lookup (including the IDENT struct) points
58 to malloc'd data, which can be freed with a call to ident_free.
59 ident_lookup returns 0 on error or timeout. Presently, this should nor‐
60 mally be taken to mean that the remote site is not running an IDENT
61 server, but it might naturally be caused by other network related prob‐
62 lems as well. Note that all fields of the IDENT struct need not neces‐
63 sarily be set.
64 ident_id takes the same parameters as ident_lookup but only returns a
66 pointer to a malloc'd area containing the identifier string, which is
67 probably the most wanted data from the IDENT query. You should free()
68 the result manually.
69 ident_free frees all data areas associated with the IDENT struct
71 pointed to by id, including the struct itself.
72 Low-level calls
74 The low-level calls can be used when greater flexibility is needed. For
76 example, if non-blocking I/O is needed, or multiple queries to the same
77 host are to be made.
78 id_open_addr and id_open both open a connection to the remote IDENT
80 server referred to by faddr. The timeout is specified by timeout. A
81 null-pointer means wait indefinitely, while a pointer to a zero-valued
82 timeval struct sets non-blocking I/O, in the same way as for select(2).
83 id_open_addr and id_open return a pointer to an id_t data, which is an
84 opaque structure to be used as future reference to the opened connec‐
85 tion. When using non-blocking I/O it might however be useful to access
86 the underlying socket file descriptior, which can be gotten at through
87 the id_fileno macro described below. While id_open only works with
88 IPv4 32-bits addresses, id_open_addr expects complete sockaddr struc‐
89 tures. At the moment, it supports sockaddr_in (AF_INET) and sock‐
90 addr_in6 (AF_INET6) structures. id_open_addr was first introduced in
91 libident version 0.30.
92 id_close closes the connection opened with id_open and frees all data
94 associated with id.
95 id_query sends off a query to a remote IDENT server. lport and fport
97 are sent to the server to identify the connection for which identifica‐
98 tion is needed. timeout is given as for id_open. If successful,
99 id_query returns the number of bytes sent to the remote server. If not,
100 -1 is returned and errno is set.
101 id_parse parses the reply to a query sent off by id_query and returns
103 information to the locations pointed to by lport, fport, identifier,
104 opsys and charset. For string data (identifier, opsys and charset)
105 pointers to malloc'd space are returned.
106 id_parse returns:
108 1 If completely successful.
110 -3 Illegal reply type from remote server. identifier is set
112 to the illegal reply.
113 -2 Cannot parse the reply from the server. identifier is
115 normally set to the illegal reply.
116 -1 On general errors or timeout.
118 0 When non-blocking mode is set and id_parse has not fin‐
120 ished parsing the reply from the remote server.
121 2 Indicates the query/reply were successful, but the remote
123 server experienced some error. identifier is set to the
124 error message from the remote server.
125 For all errors, errno is set as appropriate.
127 id_fileno is a macro that takes an id_t handle and returns the actual
129 socket file descriptor used for the connection to the remote server.
130
132 ETIMEDOUT The call timed out and non-blocking I/O was not set.
133
135 Here's an example how to handle the reply from id_reply() in the case
136 that non-blocking I/O is set. Note that id_reply() will return 0 as
137 long as it's not finished parsing a reply.
138 int rcode;
140 id_t idp;
141 /* ... */
143 idp = id_open_addr(...);
145 if (idp == NULL)
146 {
147 perror ("id_open_addr");
148 /* ... */
149 }
150 /* ... */
152 while ((rcode = id_parse(idp, timeout,
154 &lport, &fport, &id, &op, &cs)) == 0)
155 ;
156 if (rcode < 0)
158 {
159 if (errno == ETIMEDOUT)
160 foo(); /* Lookup timed out */
161 else
162 bar(); /* Fatal error */
163 }
164 else if (rcode == 1)
165 {
166 /* Valid USERID protocol reply */
167 }
168 else if (rcode == 2)
169 {
170 /* Protocol ERROR reply */
171 }
172
174 RFC-1413, socket(2), select(2)
175
177 Peter Eriksson <pen@lysator.liu.se>
178 P"ar Emanuelsson <pell@lysator.liu.se>
179 Rémi Denis-Courmont <rdenis (at) simphalempin (dot) com>
180
182 For ident_lookup and ident_id the blocking time in extreme cases might
183 be as much as three times the value given in the timeout parameter.
184Lysator ACS 11 August 2003 IDENT(3)