chiark - git - mdw - mLib/blob - sel/ident.3

   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 .PP
  12 .B "typedef struct { ...\& } ident_request;"
  13 .PP
  14 .ta 2n +2n
  15 .B "enum ["
  16 .B "    IDENT_USERID = ...,"
  17 .B "    IDENT_ERROR = ...,"
  18 .B "    IDENT_BAD = ..."
  19 .B "};"
  20 .PP
  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 .PP
  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>