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

   1 .\" -*-nroff-*-
   2 .TH ident 3 "2 October 1999" mLib
   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@nsict.org>