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