FreeBSD Manual Pages
IDENT(3) Library Functions Manual IDENT(3) NAME ident_lookup, ident_id, ident_free, id_open_addr, 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 ident_t *id_open_addr (const struct sockaddr *laddr, const struct sockaddr *faddr, struct timeval *timeout) ident_t *id_open(const struct in_addr *laddr, const struct in_addr *faddr, struct timeval *timeout) int id_close(ident_t *id) int id_query(ident_t *id, int lport, int fport, struct timeval *timeout) int id_parse(ident_t *id, struct timeval *timeout, int *lport, int *fport, char **identifier, char **opsys, char **charset) int id_fileno(ident_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 de- scriptor. timeout is the longest permissible time to block waiting for an answer, and is given in seconds. A value of 0 (zero) means wait in- definitely (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 nor- mally be taken to mean that the remote site is not running an IDENT server, but it might naturally be caused by other network related prob- lems as well. Note that all fields of the IDENT struct need not neces- sarily 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. You should free() the result manually. 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_addr and id_open both open 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_addr and id_open return a pointer to an id_t data, which is an opaque structure to be used as future reference to the opened connec- tion. 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. While id_open only works with IPv4 32-bits addresses, id_open_addr expects complete sockaddr struc- tures. At the moment, it supports sockaddr_in (AF_INET) and sock- addr_in6 (AF_INET6) structures. id_open_addr was first introduced in libident version 0.30. 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 identifica- tion 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 fin- ished 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; id_t idp; /* ... */ idp = id_open_addr(...); if (idp == NULL) { perror ("id_open_addr"); /* ... */ } /* ... */ 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> Rmi Denis-Courmont <rdenis (at) simphalempin (dot) com> 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. Lysator ACS 11 August 2003 IDENT(3)
NAME | SYNOPSIS | DESCRIPTION | ERRORS | EXAMPLES | SEE ALSO | AUTHORS | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ident&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>