From 83856ddea00e19a13be185226b98e14de9447b41 Mon Sep 17 00:00:00 2001 Message-Id: <83856ddea00e19a13be185226b98e14de9447b41.1715289109.git.mdw@distorted.org.uk> From: Mark Wooding Date: Mon, 4 Oct 1999 21:53:26 +0000 Subject: [PATCH] New modules. Organization: Straylight/Edgeware From: mdw --- man/.cvsignore | 8 ++++ man/bres.3 | 117 +++++++++++++++++++++++++++++++++++++++++++++++ man/ident.3 | 120 +++++++++++++++++++++++++++++++++++++++++++++++++ man/mLib.3 | 10 +++++ 4 files changed, 255 insertions(+) create mode 100644 man/bres.3 create mode 100644 man/ident.3 diff --git a/man/.cvsignore b/man/.cvsignore index ab2c5a2..e42f0bc 100644 --- a/man/.cvsignore +++ b/man/.cvsignore @@ -69,6 +69,11 @@ U8.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 @@ -103,6 +108,8 @@ hash_extend.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 @@ -111,6 +118,7 @@ lbuf_snarf.3 links lock_file.3 moan.3 +pquis.3 sel_addfile.3 sel_addhook.3 sel_addtimer.3 diff --git a/man/bres.3 b/man/bres.3 new file mode 100644 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 " + +.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, diff --git a/man/ident.3 b/man/ident.3 new file mode 100644 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 " + +.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, diff --git a/man/mLib.3 b/man/mLib.3 index 3d36213..28fd020 100644 --- 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. +.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), +.BR bres (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 ident (3), .BR lbuf (3), .BR lock (3), .BR mdwopt (3), -- [mdw]