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
hash_mkiter.3
hash_next.3
hash_remove.3
+ident_abort.3
+ident_socket.3
lbuf_close.3
lbuf_flush.3
lbuf_free.3
links
lock_file.3
moan.3
+pquis.3
sel_addfile.3
sel_addhook.3
sel_addtimer.3
--- /dev/null
+.\" -*-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>
--- /dev/null
+.\" -*-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>
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),
.BR exc (3),
.BR fdflags (3),
.BR hash (3),
+.BR ident (3),
.BR lbuf (3),
.BR lock (3),
.BR mdwopt (3),
~mdw / mLib / commitdiff