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