New modules.

diff --git a/man/.cvsignore b/man/.cvsignore
index ab2c5a2b6e54321383f98b845d5d3ac83a07a11c..e42f0bc19eeb59eb3d4179e50d51f603db80d911 100644 (file)
--- a/man/.cvsignore
+++ b/man/.cvsignore
@@ -69,6 +69,11 @@ U8.3
 base64_decode.3
 base64_encode.3
 base64_init.3
 base64_decode.3
 base64_encode.3
 base64_init.3

+bres_abort.3
+bres_byaddr.3
+bres_byname.3
+bres_exec.3
+bres_init.3

 conn_init.3
 conn_kill.3
 die.3
 conn_init.3
 conn_kill.3
 die.3


@@ -103,6 +108,8 @@ hash_extend.3
 hash_mkiter.3
 hash_next.3
 hash_remove.3
 hash_mkiter.3
 hash_next.3
 hash_remove.3

+ident_abort.3
+ident_socket.3

 lbuf_close.3
 lbuf_flush.3
 lbuf_free.3
 lbuf_close.3
 lbuf_flush.3
 lbuf_free.3


@@ -111,6 +118,7 @@ lbuf_snarf.3
 links
 lock_file.3
 moan.3
 links
 lock_file.3
 moan.3

+pquis.3

 sel_addfile.3
 sel_addhook.3
 sel_addtimer.3
 sel_addfile.3
 sel_addhook.3
 sel_addtimer.3

diff --git a/man/bres.3 b/man/bres.3
new file mode 100644 (file)
index 0000000..39196a8
--- /dev/null
+++ b/man/bres.3
@@ -0,0 +1,117 @@
+.\" -*-nroff-*-
+.TH bres 3 "1 October 1999" mLib
+.SH NAME
+bres \- background name resolver
+.\" @bres_abort
+.\" @bres_byname
+.\" @bres_byaddr
+.\" @bres_exec
+.\" @bres_init
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/bres.h>"
+
+.BI "void bres_byname(bres_client *" rc ", const char *" name ,
+.BI "                 void (*" func ")(struct hostent *" h ", void *" p ),
+.BI "                 void *" p );
+.BI "void bres_byaddr(bres_client *" rc ", struct inaddr " addr ,
+.BI "                 void (*" func ")(struct hostent *" h ", void *" p ),
+.BI "                 void *" p );
+.BI "void bres_abort(bres_client *" rc );
+.BI "void bres_exec(const char *" file );
+.BI "void bres_init(sel_state *" sel );
+.fi
+.SH DESCRIPTION
+The
+.B bres.h
+header file declares types and functions for doing translation between
+host names and IP addresses in the background.
+.PP
+The system must be initialized before use by a call to
+.BR bres_init ,
+passing it the address of an I/O multiplexor (see
+.BR sel (3)).
+.PP
+A resolver task is stored in an object of type
+.BR bres_client ,
+the storage for which is allocated by the caller.  The object is a
+structure, and its contents are unspecified.  The object is initialized
+by one of the name resolution functions
+.B bres_byname
+and
+.BR bres_byaddr .
+Each function is passed the following arguments:
+.TP
+.BI "bres_client *" rc
+Pointer to the client block to initialize and store the resolver job's
+state.
+.TP
+.BI "struct in_addr " addr "\fR (\fBbres_byaddr\fR)"
+.sp -1
+.TP
+.BI "const char *" name "\fR (\fBbres_byname\fR)"
+The IP address or hostname to resolve.
+.TP
+.BI "void (*" func ")(struct hostent *" h ", void *" p )
+A handler function to call when the resolver job is complete.
+.TP
+.BI "void *" p
+A pointer argument to pass to the handler function.
+.PP
+The
+.B bres_client
+block must not be discarded until either the job is complete (i.e., the
+handler function has been called) or
+.B bres_abort
+is called on it.
+.PP
+The handler function is passed either the address of a
+.B "struct hostent"
+structure describing the resolved host, or a null pointer indicating
+failure.  The
+.B hostent
+structure is as returned by the standard
+.BR gethostbyname (3)
+and
+.BR gethostbyaddr (3)
+functions.  This isn't the most convenient format for the results, but
+it does have the benefit of being standard.  Similarly, errors are
+reported through the global
+.B h_errno
+variable.
+.PP
+The function
+.B bres_abort
+cancels a running resolver job.  When it returns, the client structure
+is safe to discard.
+.PP
+The resolver is currently implemented using a pool of server processes.
+Incoming resolver jobs are passed to an available server, or a new
+server is started if all are busy.  There is a maximum number of
+servers, and jobs are queued once this limit is reached.  Old servers
+which have been idle for a period of time are killed off.  Servers are
+also killed if they start misbehaving or their jobs are aborted.
+.PP
+By default, servers are started simply by calling
+.BR fork (2).
+This can cause undesirably high memory usage in large programs.  The
+function
+.B bres_exec
+requests the resolver system to
+.BR exec (2)
+a small dedicated server program to perform name lookups to reduce
+memory consumption.  The argument to
+.B bres_exec
+is the full pathname of the server program, or null to accept the
+default set at library configuration time (which is usually correct).
+.PP
+For security reasons, when an address is resolved, the hostname received
+is verified by performing a forward lookup.  If the forward lookup fails
+to return the expected IP address, an error is reported.
+.SH "SEE ALSO"
+.BR gethostbyname (3),
+.BR gethostbyaddr (3),
+.BR sel (3),
+.BR mLib (3).
+.SH "AUTHOR"
+Mark Wooding, <mdw@nsict.org>

diff --git a/man/ident.3 b/man/ident.3
new file mode 100644 (file)
index 0000000..94b06f1
--- /dev/null
+++ b/man/ident.3
@@ -0,0 +1,120 @@
+.\" -*-nroff-*-
+.TH ident 3 "2 October 1999" mLib
+.SH "NAME"
+ident \- identd (RFC931) client
+.\" @ident_abort
+.\" @ident
+.\" @ident_socket
+.SH "SYNOPSIS"
+.nf
+.B "#include <mLib/ident>"
+
+.BI "void ident_abort(ident_request *" rq );
+.BI "void ident(ident_request *" rq ", sel_state *" s ,
+.BI "           const struct sockaddr_in *" local ,
+.BI "           const struct sockaddr_in *" remote ,
+.BI "           void (*" func ")(ident_reply *" i ", void *" p ),
+.BI "           void *" p );
+.BI "void ident_socket(ident_request *" rq ", sel_state *" s ", int " sk ,
+.BI "                  void (*" func ")(ident_reply *" i ", void *" p ),
+.BI "                  void *" p );
+.fi
+.SH "DESCRIPTION"
+The
+.B ident.h
+header defines some types and functions which implement an ident client
+(as specified by RFC931).
+.PP
+The state of an ident request in progress is represented in an object of
+type
+.BR ident_request ,
+a structure type whose layout is unspecified.  Storage for these objects
+is provided by the caller.
+.PP
+The primary interface for starting an ident request is the
+.B ident
+function.  It takes a number of arguments:
+.TP
+.BI "ident_request *" rq
+Pointer to the client request block which is to maintain the state of
+the request as it progresses.  This must not be discarded while the
+request is in progress, for obvious reasons.
+.TP
+.BI "sel_state *" s
+Pointer to an I/O multiplexor.  See
+.BR sel (3)
+for more information about the I/O multiplexing system.
+.TP
+.BI "struct sockaddr_in *" local ", *" remote
+The local and remote socket addresses describing the connection to be
+enquired about.  The local address is not optional.  If you don't have
+it handy, you can use
+.B ident_socket
+described below.
+.TP
+.BI "void (*" func ")(ident_reply *" i ", void *" p )
+The handler function to be called with the result of the ident request.
+The
+.B ident_reply
+structure is described in detail below.
+.TP
+.BI "void *" p
+A pointer argument to be supplied to the handler function.
+.PP
+The
+.B ident_socket
+function provides an alternative interface to setting up an ident
+request.  Instead of the local and remote socket addresses, the function
+works out the local and remote addresses from a socket file descriptor
+provided as an argument.
+.PP
+The handler function is provided the results in a structure of type
+.BR ident_reply .
+The pointer may be null if there was a problem connecting to the server;
+in this case, the global
+.B errno
+variable describes the problem in its usual inimitable way.
+.PP
+The reply structure contains the following members:
+.TP
+.B "unsigned short sport, dport"
+The source and destination ports, as seen from the point of view of the
+server.  These should match up with the ports in the request structure.
+.TP
+.B "unsigned type"
+The type of response received from the server.  There are three possible
+values:
+.B IDENT_USERID
+indicates that the server specified a userid and operating system name;
+.B IDENT_ERROR
+indicates that the server reported an error message; and
+.B IDENT_BAD
+indicates that the server's response was invalid.
+.TP
+.B "char *u.userid.os"
+The name of the remote operating system; only valid if
+.B type
+has the value
+.BR IDENT_USERID .
+.TP
+.B "char *u.userid.user"
+The name of the remote user; only valid if
+.B type
+has the value
+.BR IDENT_USERID .
+.TP
+.B "char *u.error"
+The error message reported by the server; only valid if
+.B type
+has the value
+.BR IDENT_ERROR .
+.PP
+An ident request in progress can be aborted by calling
+.B ident_abort
+on the request block.  In this case, no notification is made to the
+handler function.
+.SH "SEE ALSO"
+.BR sel (3),
+.BR mLib (3).
+.SH "AUTHOR"
+Mark Wooding, <mdw@nsict.org>

diff --git a/man/mLib.3 b/man/mLib.3
index 3d36213dac751b10a84283b6f0a2e1c3f308f7f7..28fd0204b8158f1f642afbe5390cc91465a60dab 100644 (file)
--- a/man/mLib.3
+++ b/man/mLib.3
@@ -209,10 +209,19 @@ module introduces signal handling into the multiplexed I/O world.
 Signals are queued until dispatched through the normal
 .B sel
 mechanism.
 Signals are queued until dispatched through the normal
 .B sel
 mechanism.

+.PP
+The
+.BR ident (3)
+module provides a nonblocking ident (RFC931) client.
+.PP
+The
+.BR bres (3)
+module does background hostname and address resolution.

 .SH "SEE ALSO"
 .BR alloc (3),
 .BR base64 (3),
 .BR bits (3),
 .SH "SEE ALSO"
 .BR alloc (3),
 .BR base64 (3),
 .BR bits (3),

+.BR bres (3),

 .BR conn (3),
 .BR crc32 (3),
 .BR dspool (3),
 .BR conn (3),
 .BR crc32 (3),
 .BR dspool (3),


@@ -221,6 +230,7 @@ mechanism.
 .BR exc (3),
 .BR fdflags (3),
 .BR hash (3),
 .BR exc (3),
 .BR fdflags (3),
 .BR hash (3),

+.BR ident (3),

 .BR lbuf (3),
 .BR lock (3),
 .BR mdwopt (3),
 .BR lbuf (3),
 .BR lock (3),
 .BR mdwopt (3),