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

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for RFC931 client
   4 .\"
   5 .\" (c) 1999, 2001, 2005, 2009, 2023, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH ident 3mLib "2 October 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @ident_abort
  33 .\" @ident
  34 .\" @ident_socket
  35 .
  36 .\"--------------------------------------------------------------------------
  37 .SH "NAME"
  38 ident \- identd (RFC931) client
  39 .
  40 .\"--------------------------------------------------------------------------
  41 .SH "SYNOPSIS"
  42 .
  43 .nf
  44 .B "#include <mLib/ident>"
  45 .PP
  46 .B "typedef struct { ...\& } ident_request;"
  47 .PP
  48 .ta 2n +2n
  49 .B "enum ["
  50 .B "    IDENT_USERID = ...,"
  51 .B "    IDENT_ERROR = ...,"
  52 .B "    IDENT_BAD = ..."
  53 .B "};"
  54 .PP
  55 .B "typedef struct {"
  56 .B "    unsigned short sport, dport;"
  57 .B "    unsigned type;"
  58 .B "    union {"
  59 .B "            struct { char *os, *user; } userid;"
  60 .B "            char *error;"
  61 .B "    } u;"
  62 .B "} ident_reply;"
  63 .PP
  64 .BI "void ident_abort(ident_request *" rq );
  65 .ta \w'\fBvoid ident('u
  66 .BI "void ident(ident_request *" rq ", sel_state *" s ,
  67 .BI "   const struct sockaddr_in *" local ,
  68 .BI "   const struct sockaddr_in *" remote ,
  69 .BI "   void (*" func ")(ident_reply *" i ", void *" p ),
  70 .BI "   void *" p );
  71 .ta \w'\fBvoid ident_socket('u
  72 .BI "void ident_socket(ident_request *" rq ", sel_state *" s ", int " sk ,
  73 .BI "   void (*" func ")(ident_reply *" i ", void *" p ),
  74 .BI "   void *" p );
  75 .fi
  76 .
  77 .\"--------------------------------------------------------------------------
  78 .SH "DESCRIPTION"
  79 .
  80 The
  81 .B ident.h
  82 header defines some types and functions which implement an ident client
  83 (as specified by RFC931).
  84 .PP
  85 The state of an ident request in progress is represented in an object of
  86 type
  87 .BR ident_request ,
  88 a structure type whose layout is unspecified.  Storage for these objects
  89 is provided by the caller.
  90 .PP
  91 The primary interface for starting an ident request is the
  92 .B ident
  93 function.  It takes a number of arguments:
  94 .TP
  95 .BI "ident_request *" rq
  96 Pointer to the client request block which is to maintain the state of
  97 the request as it progresses.  This must not be discarded while the
  98 request is in progress, for obvious reasons.
  99 .TP
 100 .BI "sel_state *" s
 101 Pointer to an I/O multiplexor.  See
 102 .BR sel (3)
 103 for more information about the I/O multiplexing system.
 104 .TP
 105 .BI "struct sockaddr_in *" local ", *" remote
 106 The local and remote socket addresses describing the connection to be
 107 enquired about.  The local address is not optional.  If you don't have
 108 it handy, you can use
 109 .B ident_socket
 110 described below.
 111 .TP
 112 .BI "void (*" func ")(ident_reply *" i ", void *" p )
 113 The handler function to be called with the result of the ident request.
 114 The
 115 .B ident_reply
 116 structure is described in detail below.
 117 .TP
 118 .BI "void *" p
 119 A pointer argument to be supplied to the handler function.
 120 .PP
 121 The
 122 .B ident_socket
 123 function provides an alternative interface to setting up an ident
 124 request.  Instead of the local and remote socket addresses, the function
 125 works out the local and remote addresses from a socket file descriptor
 126 provided as an argument.
 127 .PP
 128 The handler function is provided the results in a structure of type
 129 .BR ident_reply .
 130 The pointer may be null if there was a problem connecting to the server;
 131 in this case, the global
 132 .B errno
 133 variable describes the problem in its usual inimitable way.
 134 .PP
 135 The reply structure contains the following members:
 136 .TP
 137 .B "unsigned short sport, dport"
 138 The source and destination ports, as seen from the point of view of the
 139 server.  These should match up with the ports in the request structure.
 140 .TP
 141 .B "unsigned type"
 142 The type of response received from the server.  There are three possible
 143 values:
 144 .B IDENT_USERID
 145 indicates that the server specified a userid and operating system name;
 146 .B IDENT_ERROR
 147 indicates that the server reported an error message; and
 148 .B IDENT_BAD
 149 indicates that the server's response was invalid.
 150 .TP
 151 .B "char *u.userid.os"
 152 The name of the remote operating system; only valid if
 153 .B type
 154 has the value
 155 .BR IDENT_USERID .
 156 .TP
 157 .B "char *u.userid.user"
 158 The name of the remote user; only valid if
 159 .B type
 160 has the value
 161 .BR IDENT_USERID .
 162 .TP
 163 .B "char *u.error"
 164 The error message reported by the server; only valid if
 165 .B type
 166 has the value
 167 .BR IDENT_ERROR .
 168 .PP
 169 An ident request in progress can be aborted by calling
 170 .B ident_abort
 171 on the request block.  In this case, no notification is made to the
 172 handler function.
 173 .
 174 .\"--------------------------------------------------------------------------
 175 .SH "SEE ALSO"
 176 .
 177 .BR sel (3),
 178 .BR mLib (3).
 179 .
 180 .\"--------------------------------------------------------------------------
 181 .SH "AUTHOR"
 182 .
 183 Mark Wooding, <mdw@distorted.org.uk>
 184 .
 185 .\"----- That's all, folks --------------------------------------------------