| 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 | .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" |
| 120 | Mark Wooding, <mdw@distorted.org.uk> |