New modules.

[mLib] / man / ident.3

diff --git a/man/ident.3 b/man/ident.3
new file mode 100644 (file)
index 0000000..94b06f1
--- /dev/null
+++ b/man/ident.3
@@ -0,0 +1,120 @@
+.\" -*-nroff-*-
+.TH ident 3 "2 October 1999" mLib
+.SH "NAME"
+ident \- identd (RFC931) client
+.\" @ident_abort
+.\" @ident
+.\" @ident_socket
+.SH "SYNOPSIS"
+.nf
+.B "#include <mLib/ident>"
+
+.BI "void ident_abort(ident_request *" rq );
+.BI "void ident(ident_request *" rq ", sel_state *" s ,
+.BI "           const struct sockaddr_in *" local ,
+.BI "           const struct sockaddr_in *" remote ,
+.BI "           void (*" func ")(ident_reply *" i ", void *" p ),
+.BI "           void *" p );
+.BI "void ident_socket(ident_request *" rq ", sel_state *" s ", int " sk ,
+.BI "                  void (*" func ")(ident_reply *" i ", void *" p ),
+.BI "                  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@nsict.org>