@@@ wip type definitions in manpage synopses

[mLib] / sel / ident.3

.\" -*-nroff-*-
.TH ident 3 "2 October 1999" "Straylight/Edgeware" "mLib utilities library"
.SH "NAME"
ident \- identd (RFC931) client
.\" @ident_abort
.\" @ident
.\" @ident_socket
.SH "SYNOPSIS"
.nf
.B "#include <mLib/ident>"

.B "typedef struct { ...\& } ident_request;"

.B "enum ["
.B "\h'4n'IDENT_USERID = ...,"
.B "\h'4n'IDENT_ERROR = ...,"
.B "\h'4n'IDENT_BAD = ..."
.B "};"

.B "typedef struct {"
.B "\h'4n'unsigned short sport, dport;"
.B "\h'4n'unsigned type;"
.B "\h'4n'union {"
.B "\h'8n'struct { char *os, *user; } userid;"
.B "\h'8n'char *error;"
.B "\h'4n'} u;"
.B "} ident_reply;"

.BI "void ident_abort(ident_request *" rq );
.ds mT \fBvoid ident(
.BI "\*(mTident_request *" rq ", sel_state *" s ,
.BI "\h'\w'\*(mT'u'const struct sockaddr_in *" local ,
.BI "\h'\w'\*(mT'u'const struct sockaddr_in *" remote ,
.BI "\h'\w'\*(mT'u'void (*" func ")(ident_reply *" i ", void *" p ),
.BI "\h'\w'\*(mT'u'void *" p );
.ds mT \fBvoid ident_socket(
.BI "\*(mTident_request *" rq ", sel_state *" s ", int " sk ,
.BI "\h'\w'\*(mT'u'void (*" func ")(ident_reply *" i ", void *" p ),
.BI "\h'\w'\*(mT'u'void *" p );
.fi
.SH "DESCRIPTION"
The
.B ident.h
header defines some types and functions which implement an ident client
(as specified by RFC931).
.PP
The state of an ident request in progress is represented in an object of
type
.BR ident_request ,
a structure type whose layout is unspecified.  Storage for these objects
is provided by the caller.
.PP
The primary interface for starting an ident request is the
.B ident
function.  It takes a number of arguments:
.TP
.BI "ident_request *" rq
Pointer to the client request block which is to maintain the state of
the request as it progresses.  This must not be discarded while the
request is in progress, for obvious reasons.
.TP
.BI "sel_state *" s
Pointer to an I/O multiplexor.  See
.BR sel (3)
for more information about the I/O multiplexing system.
.TP
.BI "struct sockaddr_in *" local ", *" remote
The local and remote socket addresses describing the connection to be
enquired about.  The local address is not optional.  If you don't have
it handy, you can use
.B ident_socket
described below.
.TP
.BI "void (*" func ")(ident_reply *" i ", void *" p )
The handler function to be called with the result of the ident request.
The
.B ident_reply
structure is described in detail below.
.TP
.BI "void *" p
A pointer argument to be supplied to the handler function.
.PP
The
.B ident_socket
function provides an alternative interface to setting up an ident
request.  Instead of the local and remote socket addresses, the function
works out the local and remote addresses from a socket file descriptor
provided as an argument.
.PP
The handler function is provided the results in a structure of type
.BR ident_reply .
The pointer may be null if there was a problem connecting to the server;
in this case, the global
.B errno
variable describes the problem in its usual inimitable way.
.PP
The reply structure contains the following members:
.TP
.B "unsigned short sport, dport"
The source and destination ports, as seen from the point of view of the
server.  These should match up with the ports in the request structure.
.TP
.B "unsigned type"
The type of response received from the server.  There are three possible
values:
.B IDENT_USERID
indicates that the server specified a userid and operating system name;
.B IDENT_ERROR
indicates that the server reported an error message; and
.B IDENT_BAD
indicates that the server's response was invalid.
.TP
.B "char *u.userid.os"
The name of the remote operating system; only valid if
.B type
has the value
.BR IDENT_USERID .
.TP
.B "char *u.userid.user"
The name of the remote user; only valid if
.B type
has the value
.BR IDENT_USERID .
.TP
.B "char *u.error"
The error message reported by the server; only valid if
.B type
has the value
.BR IDENT_ERROR .
.PP
An ident request in progress can be aborted by calling
.B ident_abort
on the request block.  In this case, no notification is made to the
handler function.
.SH "SEE ALSO"
.BR sel (3),
.BR mLib (3).
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>