chiark / gitweb /
Manpages: Move manpages (back?) into the top-level directory.
[mLib] / ident.3
CommitLineData
83856dde 1.\" -*-nroff-*-
fbf20b5b 2.TH ident 3 "2 October 1999" "Straylight/Edgeware" "mLib utilities library"
83856dde 3.SH "NAME"
4ident \- identd (RFC931) client
5.\" @ident_abort
6.\" @ident
7.\" @ident_socket
8.SH "SYNOPSIS"
9.nf
10.B "#include <mLib/ident>"
11
12.BI "void ident_abort(ident_request *" rq );
13.BI "void ident(ident_request *" rq ", sel_state *" s ,
14.BI " const struct sockaddr_in *" local ,
15.BI " const struct sockaddr_in *" remote ,
16.BI " void (*" func ")(ident_reply *" i ", void *" p ),
17.BI " void *" p );
18.BI "void ident_socket(ident_request *" rq ", sel_state *" s ", int " sk ,
19.BI " void (*" func ")(ident_reply *" i ", void *" p ),
20.BI " void *" p );
21.fi
22.SH "DESCRIPTION"
23The
24.B ident.h
25header defines some types and functions which implement an ident client
26(as specified by RFC931).
27.PP
28The state of an ident request in progress is represented in an object of
29type
30.BR ident_request ,
31a structure type whose layout is unspecified. Storage for these objects
32is provided by the caller.
33.PP
34The primary interface for starting an ident request is the
35.B ident
36function. It takes a number of arguments:
37.TP
38.BI "ident_request *" rq
39Pointer to the client request block which is to maintain the state of
40the request as it progresses. This must not be discarded while the
41request is in progress, for obvious reasons.
42.TP
43.BI "sel_state *" s
44Pointer to an I/O multiplexor. See
45.BR sel (3)
46for more information about the I/O multiplexing system.
47.TP
48.BI "struct sockaddr_in *" local ", *" remote
49The local and remote socket addresses describing the connection to be
50enquired about. The local address is not optional. If you don't have
51it handy, you can use
52.B ident_socket
53described below.
54.TP
55.BI "void (*" func ")(ident_reply *" i ", void *" p )
56The handler function to be called with the result of the ident request.
57The
58.B ident_reply
59structure is described in detail below.
60.TP
61.BI "void *" p
62A pointer argument to be supplied to the handler function.
63.PP
64The
65.B ident_socket
66function provides an alternative interface to setting up an ident
67request. Instead of the local and remote socket addresses, the function
68works out the local and remote addresses from a socket file descriptor
69provided as an argument.
70.PP
71The handler function is provided the results in a structure of type
72.BR ident_reply .
73The pointer may be null if there was a problem connecting to the server;
74in this case, the global
75.B errno
76variable describes the problem in its usual inimitable way.
77.PP
78The reply structure contains the following members:
79.TP
80.B "unsigned short sport, dport"
81The source and destination ports, as seen from the point of view of the
82server. These should match up with the ports in the request structure.
83.TP
84.B "unsigned type"
85The type of response received from the server. There are three possible
86values:
87.B IDENT_USERID
88indicates that the server specified a userid and operating system name;
89.B IDENT_ERROR
90indicates that the server reported an error message; and
91.B IDENT_BAD
92indicates that the server's response was invalid.
93.TP
94.B "char *u.userid.os"
95The name of the remote operating system; only valid if
96.B type
97has the value
98.BR IDENT_USERID .
99.TP
100.B "char *u.userid.user"
101The name of the remote user; only valid if
102.B type
103has the value
104.BR IDENT_USERID .
105.TP
106.B "char *u.error"
107The error message reported by the server; only valid if
108.B type
109has the value
110.BR IDENT_ERROR .
111.PP
112An ident request in progress can be aborted by calling
113.B ident_abort
114on the request block. In this case, no notification is made to the
115handler function.
116.SH "SEE ALSO"
117.BR sel (3),
118.BR mLib (3).
119.SH "AUTHOR"
9b5ac6ff 120Mark Wooding, <mdw@distorted.org.uk>