diff options
Diffstat (limited to 'rpc++/rpc++.texi')
-rw-r--r-- | rpc++/rpc++.texi | 1519 |
1 files changed, 0 insertions, 1519 deletions
diff --git a/rpc++/rpc++.texi b/rpc++/rpc++.texi deleted file mode 100644 index 71ed33017b7..00000000000 --- a/rpc++/rpc++.texi +++ /dev/null @@ -1,1519 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@tex -% They are redefined in texinfo, but I need them -\gdef\`#1{{\accent18 #1}} -\gdef\'#1{{\accent19 #1}} -\gdef\[{{[}} -\gdef\]{{]}} -@end tex -@comment %**start of header (This is for running Texinfo on a region.) -@setfilename rpc++.info -@settitle A C++ Interface to Remote Procedure Calls -@setchapternewpage on -@comment %**end of header (This is for running Texinfo on a region.) - -@c You'll have to define the following additional texinfo-formats to -@c run texinfo on this file. -@c -@c (put '\& 'texinfo-format 'texinfo-format-\&) -@c (defun texinfo-format-\& () -@c (texinfo-discard-command) -@c (insert "&")) -@c -@c (put '\[ 'texinfo-format 'texinfo-format-\[) -@c (defun texinfo-format-\[ () -@c (texinfo-discard-command) -@c (insert "[")) -@c -@c (put '\] 'texinfo-format 'texinfo-format-\]) -@c (defun texinfo-format-\] () -@c (texinfo-discard-command) -@c (insert "]")) - -@ifinfo -This file documents a C++ interface to Sun remote procedure calls. - -Copyright @copyright{} 1992 Michael N. Lipp -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through @TeX{} and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU Library General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU Library General Public License'' and -this permission notice may be included in translations approved by the -Free Software Foundation instead of in the original English. -@end ifinfo - -@titlepage - -@title A C++ Interface -@title to Sun Remote Procedure Calls -@sp 1 -@subtitle @authorfont{by Michael N. Lipp} -@sp 20 -@subtitle{for version 2.2} -@subtitle{Technische Hochschule Darmstadt, Institut f@"ur Datentechnik} - -@comment The following two commands start the copyright page. -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1992 Michael N. Lipp - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU Library General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU Library General Public License'' may be -included in a translation approved by the author instead of in the original -English. -@end titlepage - -@node Top, Overview, (dir), (dir) - -@menu -* Overview:: Overview -* Installation:: Installation -* Classes:: The Classes -* Caveats:: Caveats -* References:: References -* Copying:: GNU LIBRARY GENERAL PUBLIC LICENSE -* Data Type Index:: Data Type Index -* Function Index:: Function and Method Index -* Concept Index:: Concept Index - - --- The Detailed Node Listing --- - -The classes - -* XdrInfo:: @code{XdrInfo} -* RpcRequest:: @code{RpcRequest} -* Callbacks:: @code{Callbacks} -* RpcService:: @code{RpcService} -* RpcStub:: @code{RpcStub} - -Callbacks - -* RpcCallback:: @code{RpcCallback} -* RpcMethodCall:: @code{RpcMethodCall} -* Calling Conventions:: @code{Calling Conventions} - -Caveats - -* Global objects:: Global objects -* Destruction rules:: Destruction rules -* Matching server and clients:: Matching server and clients -@end menu - -@node Overview, Installation, Top, Top -@comment node-name, next, previous, up -@chapter Overview -@cindex Overview - -This document describes my C++ interface to Sun Remote Procedure Calls. -It is based on sources from Peter Bersen that I got from some newsgroup, -though I don't remember which one. I liked the basic idea but disliked -several aspects of the interface details. So I adapted it to my likes. I -intended some minor changes but soon found myself renaming classes, -changing method parameters, introducing new classes, etc. The result is -by no way compatible with the original version. It is, I hope, -nevertheless useful. - -Basically, the interface defines six class: @code{XdrInfo}, -@code{RpcRequest}, @code{RpcCallback}/@code{RpcMethodCall}, -@code{RpcService} and @code{RpcStub}. - -@code{XdrInfo} objects describe the external data representation of a -type. There are predefined @code{XdrInfo}s for the basic types. -@code{RpcRequest} objects describe the available procedure calls. They -are constructed from a unique request number, the @code{XdrInfo}s of the -procedure's arguments and its return type. @code{RpcCallback} is an -object that holds a pointer to a function and information about the -number of its arguments. @code{RpcMethodCall} is a template that in a -similar way holds a pointer to an object and one of its methods and -Information about the number of its arguments. - -An @code{RpcRequest} and its matching @code{RpcCallback} or -@code{RpcMethodCall} may be registered with an @code{RpcService}. -Exactly one object of type @code{RpcService} may be instantiated in a -program that implements an RPC server. Method @code{Provide ()} is a -loop that waits for requests and dispatches them. - -A client program instantiates an object of type @code{RpcStub}. The -constructor establishes a connection to the server specified by its -arguments. Procedures of the server may be invoked using method -@code{Call (@dots{})}. - -@node Installation, Classes, Overview, Top -@comment node-name, next, previous, up -@chapter Installation -@cindex Installation - -The rpc++ library has successfully been tested using a patched gcc-2.2.2 -on a SparcStation running SunOS 4.1.[12] and a 386 system running -Interactive Unix (a SYSV 3.2). Patching gcc-2.2.2 was necessary because -the unpatched version can't handle typedefs that are local to templates. -The bug report with patches can be found in the source directory in file -@code{gcc-2.2.2.fix}. - -As a prerequisite to using RPCs with C++ you need ANSI-C/C++ conformant -header files for RPC. I have provided such files in the directory -@code{StdHdrs/rpc} of the source tree. To avoid any copyright conflicts, -they are derived from the public available RPC source code rather than -from the files that come with SunOS 4.1.X. The differences are minor. -The SunOS 4.1.X files define some additional functions. You have to -either copy the files from @code{StdHdrs/rpc} or patched files from your -@code{/usr/include/rpc} to a directory where gcc can find them. If you -don't want to install them globally in gcc's include directory, you can -include them by using an additional ``@code{-I}'' flag during -compilation. - -In SunOS you can simply type `@code{make install INSTROOT=@dots{}}' -which will make the library and install it in @code{INSTROOT/lib} and -the header files in @code{INSTROOT/include/rpc++}. Other Unices will -probably have problems with the `install' command. Type only `make' and -copy the resulting @code{librpc++.a} to your local library directory and -the files @code{rpc++/*} to an @code{rpc++}-subdirectory of your local -include directory. - -@node Classes, Caveats, Installation, Top -@comment node-name, next, previous, up -@chapter The classes - -@menu -* XdrInfo:: @code{XdrInfo} -* RpcRequest:: @code{RpcRequest} -* Callbacks:: @code{Callbacks} -* RpcService:: @code{RpcService} -* RpcStub:: @code{RpcStub} -@end menu - -@node XdrInfo, RpcRequest, , Classes -@comment node-name, next, previous, up -@section @code{XdrInfo} -@cindex @code{XdrInfo} - -Declared in: @code{"rpc++/xdr++.h"} - -@deftp Class XdrInfo -Class XdrInfo describes serializers. It combines the xdrproc_t with the -size info (the size of the data to be converted) usually needed if you -want to apply a serializer. -@end deftp - -There is only one constructor for @code{XdrInfo}: - -@deftypefn Constructor {} XdrInfo (xdrproc_t @var{t}, size_t @var{s}) -Construct an @code{XdrInfo} for a type. The type can be converted to an -external data representation (serielized) with function @var{t}. Its -size (in bytes, from @code{sizeof (type)}), is @var{s}. -@end deftypefn - -The methods query the information given to the constructor: - -@deftypefn Method xdrproc_t Proc () const -Return the conversion function stored in an @code{XdrInfo}. -@end deftypefn - -@deftypefn Method size_t Size () const -Return the size of the type described by the @code{XdrInfo}. -@end deftypefn - -There are a number of predefined @code{XdrInfo}s. They are defined as -static members of a class @code{Xdr} for scoping reasons. - -@defvr XdrInfo Xdr::Xchar -The conversion and size information for a character. -@end defvr - -@defvr XdrInfo Xdr::Xshort -The conversion and size information for a short integer. -@end defvr - -@defvr XdrInfo Xdr::Xint -The conversion and size information for an integer. -@end defvr - -@defvr XdrInfo Xdr::Xlong -The conversion and size information for a long integer. -@end defvr - -@defvr XdrInfo Xdr::Xuchar -The conversion and size information for an unsigned character. -@end defvr - -@defvr XdrInfo Xdr::Xushort -The conversion and size information for an unsigned short integer. -@end defvr - -@defvr XdrInfo Xdr::Xulong -The conversion and size information for an unsigned long integer. -@end defvr - -@defvr XdrInfo Xdr::Xfloat -The conversion and size information for a float. -@end defvr - -@defvr XdrInfo Xdr::Xdouble -The conversion and size information for a double. -@end defvr - -@defvr XdrInfo Xdr::Xenum_t -The conversion and size information for any enumeration type. -@end defvr - -@defvr XdrInfo Xdr::Xbool_t -The conversion and size information for a bool. -@end defvr - -@defvr XdrInfo Xdr::Xvoid -A special @code{XdrInfo} for the return type of a procedure that returns -nothing. -@end defvr - -@defvr XdrInfo Xdr::Xnull -A special @code{XdrInfo} for the return type of a procedure that is to -be executed batched or asynchronously (@pxref{RpcRequest}). -@end defvr - -@page -@node RpcRequest, Callbacks, XdrInfo, Classes -@comment node-name, next, previous, up -@section @code{RpcRequest} -@cindex @code{RpcRequest} - -Declared in: @code{"rpc++/request.h"} - -@deftp Class RpcRequest -RpcRequest is a class that specifies a request for a procedure that is -part of (registered with) a service. -@end deftp - -There are several constructors for @code{RpcRequest}. They vary in the -number of @code{XdrInfo}s used to describe the input parameters of the -procedure. - -@deftypefn Constructor {} RpcRequest (u_long @var{reqid}, const XdrInfo* @var{out}, ReqType @var{t}=normal) -@end deftypefn -@deftypefn Constructor {} RpcRequest (u_long @var{reqid}, const XdrInfo* @var{out}, const XdrInfo* @var{in1}, ReqType @var{t}=normal) -@end deftypefn -@deftypefn Constructor {} RpcRequest (u_long @var{reqid}, const XdrInfo* @var{out}, const XdrInfo* @var{in1}, const XdrInfo* @var{in2}, ReqType @var{t}=normal) -These constructors construct an @code{RpcRequest} for a procedure with -zero, one or two arguments. Additional similar constructors are defined -for procedures with up to seven arguments. @var{reqid} uniquely -identifies the request (the procedure of the server). @var{reqid} may -not be 0. The @code{XdrInfo*}s following @var{reqid} specify the types of -the input parameters. They are followed by the @code{XdrInfo*} that -describes the type of the value returned by the RPC. If no value is -returned, @code{&Xdr::Xvoid} must be given as argument -(@pxref{XdrInfo}). The final optional argument @var{t} specifies the -call mode: @code{RpcRequest::normal}, @code{RpcRequest::batched} or -@code{RpcRequest::async} (see below). -@end deftypefn - -@deftypefn Constructor {} RpcRequest (u_long @var{reqid}, const XdrInfo* @var{out}, const XdrInfo** @var{intypes}, ReqType @var{t}=normal) -This constructor can be used to construct an @code{RpcRequest} with an -arbitrary number of arguments. The pointers to @code{XdrInfo} are passed -in an array. The number of elements in the array must be one more than -the number of parameters and the last element must be zero. -@end deftypefn - -If the request type @var{t} is @code{RpcRequest::normal}, method -@code{Call} (@pxref{RpcStub}) assembles the message to the server, sends -it, waits for a reply and returns the result. - -If the request type is @code{RpcRequest::batched}, method -@code{RpcStub::Call} assembles the message to the server and puts it in -a buffer. Messages are only flushed if the buffer is full or -@code{RpcStub::Call} is used with a @code{normal} or @code{async} -request. - -If the request type is @code{RpcRequest::async}, method -@code{RpcStub::Call} (@pxref{RpcStub}) assembles the message to the -server and sends it, as with @code{normal}. It does, however, not wait -for a result. Mode @code{async} is implemented by calling the underlying -RPC--function @code{clnt_call} with a timeout of zero. - -As in both non--normal cases (@code{batched} and @code{async}) -@code{RpcStub::Call} does not wait for a return value from the server, -the return type of the @code{RpcRequest} must be specified as -@code{&Xdr::Xnull}. - -Note that requests that are registered for a service are stored in an -array using the request identification as the index, so keep ids small. - -Normally, requests should be specified in a header file included by both -the server and the client program (@pxref{Matching server and clients}). - -@page -@node Callbacks, RpcService, RpcRequest, Classes -@comment node-name, next, previous, up -@section Callbacks -@cindex Callbacks - -If a server receives a request from a client, it needs to know how a -particular procedure is to be invoked. This information is specified -using objects @code{RpcCallback} or @code{RpcMethodCall} when the -procedure resp.@ method is specified. - -The class -@deftp Class AnyRpcCallback -@end deftp -serves as an abstract base class for the two kinds of callbacks. - -The following sections describe the constructors for @code{RpcCallback} -and @code{RpcMethodCall} and the calling conventions for the functions -or methods called back. - -@menu -* RpcCallback:: @code{RpcCallback} -* RpcMethodCall:: @code{RpcMethodCall} -* Calling Conventions:: @code{Calling Conventions} -@end menu - -@node RpcCallback, RpcMethodCall, , Callbacks -@comment node-name, next, previous, up -@subsection @code{RpcCallback} -@cindex @code{RpcCallback} - -Declared in: @code{"rpc++/callback.h"} - -@deftp Class RpcCallback -An @code{RpcCallback} describes a function that is to be called by the -server on request from the client. -@end deftp - -@deftypefn Constructor {} RpcCallback (void* (*)() @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcCallback (void* (*)(void*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcCallback (void* (*)(void*, void*) @var{proc}) -Construct an @code{RpcCallback} for a function that takes zero, one or -two arguments and returns a result. Constructors for functions with -up to seven arguments are defined. -@end deftypefn -@deftypefn Constructor {} RpcCallback (void* (*)(void**) @var{proc}) -Construct an @code{RpcCallback} for a function that takes an arbitrary -number of arguments and returns a result. -@end deftypefn - -@deftypefn Constructor {} RpcCallback (void (*)() @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcCallback (void (*)(void*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcCallback (void (*)(void*, void*) @var{proc}) -Construct an @code{RpcCallback} for a function that takes zero, one or -two arguments and returns no result. Constructors for functions with -up to seven arguments are defined. -@end deftypefn -@deftypefn Constructor {} RpcCallback (void (*)(void**) @var{proc}) -Construct an @code{RpcCallback} for a function that takes an arbitrary -number of arguments and return no result. -@end deftypefn - -@deftypefn Constructor {} RpcCallback (void* (*)(RpcService*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcCallback (void* (*)(void*, RpcService*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcCallback (void* (*)(void*, void*, RpcService*) @var{proc}) -Construct an @code{RpcCallback} for a function that takes zero, one or -two arguments and returns a result. Constructors for functions with -up to seven arguments are defined. Upon invocation, a pointer to the -object of type @code{RpcService} that received the request and called -the function is passed as an additional argument. -@end deftypefn -@deftypefn Constructor {} RpcCallback (void* (*)(void**) @var{proc}) -Construct an @code{RpcCallback} for a function that takes an arbitrary -number of arguments and returns a result. Upon invocation, a pointer to the -object of type @code{RpcService} that received the request and called -the function is passed as an additional argument. -@end deftypefn - -@deftypefn Constructor {} RpcCallback (void (*)(RpcService*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcCallback (void (*)(void*, RpcService*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcCallback (void (*)(void*, void*, RpcService*) @var{proc}) -Construct an @code{RpcCallback} for a function that takes zero, one or -two arguments and returns a result. Constructors for functions with -up to seven arguments are defined. Upon invocation, a pointer to the -object of type @code{RpcService} that received the request and called -the function is passed as an additional argument. -@end deftypefn -@deftypefn Constructor {} RpcCallback (void (*)(void**) @var{proc}) -Construct an @code{RpcCallback} for a function that takes an arbitrary -number of arguments and returns a result. Upon invocation, a pointer to the -object of type @code{RpcService} that received the request and called -the function is passed as an additional argument. -@end deftypefn - -@node RpcMethodCall, Calling Conventions, RpcCallback, Callbacks -@comment node-name, next, previous, up -@subsection @code{RpcMethodCall} -@cindex @code{RpcMethodCall} - -Declared in: @code{"rpc++/callback.h"} - -@deftp Class RpcMethodCall -An @code{RpcMethodCall} describes a method of an object that is to be -called by the server on request from the client. -@end deftp - -@deftypefn Constructor {} RpcMethodCall <class T> (void* (T::*)() @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void* (T::*)(void*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void* (T::*)(void*, void*) @var{proc}) -Construct an @code{RpcMethodCall} for an object and one of its methods that -takes zero, one or two arguments and returns a result. Constructors for -methods with up to seven arguments are defined. -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void* (T::*)(void**) @var{proc}) -Construct an @code{RpcMethodCall} for an object and one of its methods -that takes an arbitrary number of arguments and returns a result. -@end deftypefn - -@deftypefn Constructor {} RpcMethodCall <class T> (void (T::*)() @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void (T::*)(void*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void (T::*)(void*, void*) @var{proc}) -Construct an @code{RpcMethodCall} for an object and one of its methods -that takes zero, one or two arguments and returns no result. -Constructors for methods with up to seven arguments are defined. -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void (T::*)(void**) @var{proc}) -Construct an @code{RpcMethodCall} for an object and one of its methods -that takes an arbitrary number of arguments and return no result. -@end deftypefn - -@deftypefn Constructor {} RpcMethodCall <class T> (void* (T::*)(RpcService*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void* (T::*)(void*, RpcService*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void* (T::*)(void*, void*, RpcService*) @var{proc}) -Construct an @code{RpcMethodCall} for an object and one of its methods -that takes zero, one or two arguments and returns a result. Constructors -for methods with up to seven arguments are defined. Upon invocation, a -pointer to the object of type @code{RpcService} that received the -request and called the method is passed as an additional argument. -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void* (T::*)(void**) @var{proc}) -Construct an @code{RpcMethodCall} for an object and one of its methods -that takes an arbitrary number of arguments and returns a result. Upon -invocation, a pointer to the object of type @code{RpcService} that -received the request and called the method is passed as an additional -argument. -@end deftypefn - -@deftypefn Constructor {} RpcMethodCall <class T> (void (T::*)(RpcService*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void (T::*)(void*, RpcService*) @var{proc}) -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void (T::*)(void*, void*, RpcService*) @var{proc}) -Construct an @code{RpcMethodCall} for an object and one of its methods -that takes zero, one or two arguments and returns a result. Constructors -for methods with up to seven arguments are defined. Upon invocation, a -pointer to the object of type @code{RpcService} that received the -request and called the method is passed as an additional argument. -@end deftypefn -@deftypefn Constructor {} RpcMethodCall <class T> (void (T::*)(void**) @var{proc}) -Construct an @code{RpcMethodCall} for an object and one of its methods -that takes an arbitrary number of arguments and returns a result. Upon -invocation, a pointer to the object of type @code{RpcService} that -received the request and called the method is passed as an additional -argument. -@end deftypefn - -@node Calling Conventions, , RpcMethodCall, Callbacks -@comment node-name, next, previous, up -@subsection @code{Calling Conventions} -@cindex @code{calling conventions} - -As could be seen from the parameter types in the constructors, functions -and methods that are called in response to a request from a client know -only about pointers to void as arguments and result values because their -real type is coded in the @code{RpcRequest} and not known at compile -time. The only way to avoid this is to implement some kind of rpcgen++. -However, I never liked this kind of tools and I'm willing to risk a bit -of type unsafeness in this case. - -When a procedure (or method) is called, its arguments point to values -(the variants with an arbitrary number of arguments receive an array of -pointers to values) of the types specified in the constructor of the -@code{RpcRequest} that led to the invocation of the procedure. I -recommend to access the values and assign them to local variables of the -procedure in the first statements. E.g.: -@example -void* Add (void* s1p, void* s2p) -@{ - int s1 = *(int*)s1p; - int s2 = *(int*)s2p; - ... -@end example - -The return value of the procedure is a pointer to the result. Therefore, -results may never be put in automatic variables. They must be global or -static. E.g.: -@example - ... - static int sum; - sum = s1 + s2; - return (void*)∑ -@} -@end example - -Note the special case of strings (defined as parameters or return values -using @code{Xdr::Xwrapstring}, @pxref{XdrInfo}). If you think of a -string as being defined as a type ``@code{typedef char* string}'', it is -obvious that a string is passed as argument or returned as result by a -@code{string*}, i.e., a @code{char**}. E.g.: -@example -void* Capitalize (void* strp) -@{ - static char* str; - str = *(char**)strp; - str[0] = toupper (str[0]); - return (void*)&str; -@} -@end example - -@page -@node RpcService, RpcStub, Callbacks, Classes -@comment node-name, next, previous, up -@section @code{RpcService} -@cindex @code{RpcService} - -Declared in: @code{"rpc++/service.h"} - -@deftp Class RpcService -An object of type @code{RpcService} provides the server capabilities -within a program. -@end deftp - -There are two constructors for @code{RpcService}: - -@deftypefn Constructor {} RpcService (u_long @var{prog}, u_long @var{vers}) -Construct an object representing the @var{vers}'th version of program -(service) number @code{prog}. -@end deftypefn -@deftypefn Constructor {} RpcService (u_long @var{vers}) -Construct an object representing the @var{vers}'th version of a transient -program (service). -@end deftypefn - -@deftypefn Method bool OK () -Returns TRUE if the service is ready for operation, i.e., has successfully -been established during construction. -@end deftypefn - -The number of a service, especially a transient service, can be obtained -with method @code{@w{Program ()}}: - -@deftypefn Method u_long Program () -Returns the number of the program (service). This is either the number -passed as an argument to the constructor or a number from the transient -program area. -@end deftypefn - -The next step after the construction of an @code{RpcService} is to -register the requests handled by the service: - -@deftypefn Method {virtual void} Register (const RpcRequest& @var{req}, const AnyRpcCallback& @var{cb}) -Associate request @var{req} with the procedure or object/method pair -specified by @code{cb}. The usual way to call @code{Register} is -@example -@{ - RpcService svc (...); - svc.register (addreq, RpcCallback (Add)); - ... -@} -@end example -@end deftypefn - -After all requests have been registered, the object of type -@code{RpcService} can provide the service: -@deftypefn Method void Provide () -Repeatedly wait for a request and handle it by calling the procedure or -method registered for it. -@end deftypefn - -@deftypefn Method {virtual void*} HandleError () -@code{HandleError} is a protected method that is called when an error -occurs. The cause of the error is stored in a protected member variable -@code{errorState}. If the default error handling (shown below) is not -appropriate for your application, derive your own class from -@code{RpcService} that implements a different error handling policy. If -you consider an error recoverable, reset @code{errorState} to -@code{RpcService::noError} in your error handler. Else, @code{OK ()} -keeps returning FALSE. -@example -void RpcService::HandleError () -@{ - switch (errorState) - @{ - case reconstructionAttempt: - cerr << "rpc++: Attempt to construct another instance of RpcService.\n"; - exit (1); - case cantCreateTCPService: - cerr << "rpc++: can't create tcp service.\n"; - exit(1); - case cantRegisterService: - cerr << form ("rpc++: can't register (%d, %d, tcp).", prog, vers); - exit(1); - case cantSendReply: - cerr << "rpc++: can't reply to RPC call.\n"; - break; - case invalidResult: - cerr << "rpc++: registered routine has return NULL pointer.\n"; - abort (); - case notRegistered: - cerr << "rpc++: requested RPC routine not registered.\n"; - break; - case cantGetArgs: - cerr << "rpc++: can't get procedure arguments.\n"; - break; - case cantFreeArgs: - cerr << "rpc++: can't free XDR arguments.\n"; - break; - @} - errorState = noError; -@} -@end example -@end deftypefn - -If the program that provides the service has other things to do as well, -i.e., does not only handle requests, it usually has its own main loop -that handles events. This loop must be extended to handle RPC events, -i.e., if anything happens on the RPC file descriptors, it must call -@code{svc_getreqset} just as @code{Provide ()} does. -@example -void RpcService::Provide () -@{ - int dtbsz = getdtablesize(); - fd_set readfds; - - for(;;) - @{ - readfds = svc_fdset; - switch(select (dtbsz, &readfds, 0, 0, 0)) - @{ - case -1: - if (errno != EBADF) - continue; - cerr << "PRC++: select: " << sys_errlist[errno] << '\n'; - return; - break; - case 0: - continue; - default: - svc_getreqset (&readfds); - break; - @} - @} -@} -@end example - -The following methods are only available during the execution of a -callback, i.e., they can be applied to @code{RpcService} if a pointer to -the invoking object has been declared as last parameter of a callback -routine. - -@deftypefn Method {struct sockaddr_in*} Caller () -Return the socket address information of the calling host. -@end deftypefn - -@deftypefn Method char* CallerName () -Return the name of the calling host. -@end deftypefn - -@deftypefn Method void Reply () -@end deftypefn -@deftypefn Method void Reply (void* @var{res}) -Normally, a request to the server terminates when the callback completes -(either with or without returning a value, depending on the return -type). In some cases it is desirable to reply to the client before all -the actions related to the request have been completed. This allows the -client to resume execution. The result (if any) must of course not -depend on the functions still to be executed. -@end deftypefn - -@deftypefn Method void Interrupt () -This is the proper way to terminate the loop entered by calling -@code{Provide()}. After return from the callback that invoked -@code{Interrupt()} method @code{Provide()} will return. -@end deftypefn - -@page -@node RpcStub, , RpcService, Classes -@comment node-name, next, previous, up -@section @code{RpcStub} -@cindex @code{RpcStub} - -Declared in: @code{"rpc++/stub.h"} - -@deftp Class RpcStub -An @code{RpcStub} represents the client side of a connection. -@end deftp - -There are two constructors for @code{RpcStub} that vary in the position -of their arguments only: - -@deftypefn Constructor {} RpcStub (u_long @code{prognum}, u_long @code{versnum}, char* @var{hostname}="localhost", timeval @var{timeout}=defaultTimeout, bool @var{connect}=TRUE) -@end deftypefn -@deftypefn Constructor {} RpcStub (u_long @code{prognum}, u_long @code{versnum}, char* @var{hostname}="localhost", bool @var{connect}=TRUE, timeval @var{timeout}=defaultTimeout) -Construct an @code{RpcStub} that connects to the @var{versnum}'th -version of program (service) @var{prognum} on host @var{hostname}. The -timeout for successful completion of communication operations is -@var{timeout} which defaults to 25 seconds. Unless @var{connect} is -false, the constructor makes a connection attempt. -@end deftypefn - -There are various methods: - -@deftypefn Method void Reconnect () -Connect to the server. Usually this method is called if the connection -was not to be established by the constructor or if the connection -attempt failed and is to be repeated. -@end deftypefn - -@deftypefn Method bool OK () -Returns TRUE if the stub is ready for operation, i.e., connected to a -server. -@end deftypefn - -@deftypefn Method CLIENT* Service () -Access to the standard RPC level. Returns the handle that identifies the -server. -@end deftypefn - -@deftypefn Method timeval GetTimeout () const -Returns the default timeout for network operations. -@end deftypefn - -@deftypefn Method void SetTimeout (timeval& @var{timo}) -Sets the default timeout for network operations -@end deftypefn - -@deftypefn Method void* Call (RpcRequest& @var{req}, bool @var{handle_errors}=TRUE) -@end deftypefn -@deftypefn Method void* Call (RpcRequest& @var{req}, void* @var{in1}, bool @var{handle_errors}=TRUE) -@end deftypefn -@deftypefn Method void* Call (RpcRequest& @var{req}, void* @var{in1}, @var{in2} bool @var{handle_errors}=TRUE) -Request the operation specified by @var{req} from the server, passing -zero, one or two arguments. There are declarations of this method for up -two seven arguments. Arguments are passed as pointers to the argument -values. The value returned by @code{Call} is a pointer to the result -returned by the server. The result is valid until @code{Call} is called -again. If @var{handle_errors} is FALSE and an error occurs, @code{Call} -simply returns 0. Else, it calls method @code{HandleError} (see below). -@end deftypefn -@deftypefn Method void* Call (RpcRequest& @var{req}, void** @var{invals}, bool @var{handle_errors}=TRUE) -The variant of @code{Call} that handles an arbitrary number of -arguments. Pointers to the arguments are passed in an array in -parameter @var{invals}. The size of the array must match the number of -arguments given to the constructor of @var{req}. -@end deftypefn - -@deftypefn Method {virtual void*} HandleError () -@code{HandleError} is a protected method that is called when an error -occurs. The cause of the error is stored in a protected member variable -@code{errorState}. If the default error handling policy (shown below) is -not appropriate for your application, derive your own class from -@code{RpcStub} that implements a different one. If you consider an error -recoverable, reset @code{errorState} to @code{RpcStub::noError} in your -error handler. Else, @code{OK ()} keeps returning FALSE. If an error -occurs during a @code{Call} and parameter @var{handle_errors} is TRUE, -@code{Call} invokes @code{HandleError} and returns its result as result -of the call. -@example -void* RpcStub::HandleError () -@{ - switch (errorState) - @{ - case notConnected: - cerr << "rpc++: Stub has not been connected to server.\n"; - case cantCreate: - cerr << clnt_spcreateerror ("rpc++") << '\n'; - break; - case cantCall: - cerr << clnt_sperror (svc, "rpc++") << '\n'; - exit (1); - @} - return 0; -@} -@end example -@end deftypefn - -While no or little improvement of coding quality can be gained from -deriving a service specific class from @code{RpcService}, the opposite -is true for @code{RpcStub}. A service specific derivation may define -methods that have the ``real'' argument lists instead of pointers to -void. These methods are simply implemented by casting the arguments and -(inline) calling one of the @code{Call}--methods. Apart from better -type checking, this has the advantage of keeping details like the -available @code{RpcRequest}s local to the definition of the derived -class (see the example in the @code{example}--directory). - -@node Caveats, References, Classes, Top -@comment node-name, next, previous, up -@chapter Caveats -@cindex Caveats - -@menu -* Global objects:: Global objects -* Destruction rules:: Destruction rules -* Matching server and clients:: Matching server and clients -@end menu - -@node Global objects, Destruction rules, , Caveats -@comment node-name, next, previous, up -@section Global objects -@cindex Global objects - -As a general C++ rule, be careful with global objects. The sequence of -constructor invocations for global objects is not defined. This is the -reason, why @code{RpcRequests} are constructed from pointers to -@code{XdrInfo}s rather than from @code{XdrInfo}s. - -Both @code{XdrInfo}s and @code{RpcRequest}s tend to be instantiated as -global objects or static member variables. If the constructor of -@code{RpcRequest} received @code{XdrInfo}s instead of pointers and -copied the information contained in the @code{XdrInfo} (the solution I -had preferred), it may happen that the @code{XdrInfo} has not been -constructed yet and thus contains invalid data. - -The same problem occurs if you want to define a global -``alias--@code{XdrInfo}'' matching a ``@code{typedef int myint}''. -Don't use @code{XdrInfo Xmyint (Xdr::Xint)} as this may copy the -uninitialized @code{Xdr::Xint}. Use @code{XdrInfo& Xmyint = Xdr::Xint} -instead. - -@node Destruction rules, Matching server and clients, Global objects, Caveats -@comment node-name, next, previous, up -@section Destruction rules -@cindex Destruction rules - -Objects of type @code{XdrInfo} are resources that can be used more than -once, i.e., in different @code{RpcRequest}s. If they were handled -properly, references to @code{XdrInfo} would be counted and the -@code{XdrInfo} destructed automatically if the last reference is -removed (unless it is the @code{XdrInfo} of a predefined type). - -Such a resource management for @code{XdrInfo}s has been considered -unnecessary as @code{XdrInfo}s will rarely be dynamic objects. If the -user allocates an @code{XdrInfo} on the stack or the heap, it is his -responsibility to assure that the object is valid until the last -@code{RpcResource} that uses it has been destructed. - -@node Matching server and clients, , Destruction rules, Caveats -@comment node-name, next, previous, up -@section Matching server and clients - -In order to make sure that the server and the clients agree about the -protocol, all @code{RpcRequest}s for a service should be declared in a -header file and instantiated in a corresponding source file. The header -file and the compiled source file make the ``library'' that provides the -service. Thus a server consists of three files: the server executable, a -header file defining the service that is to be included in client -sources and an object file which must be linked to the client -executable. - -@c ====================================================================== - -@node References, Copying, Caveats, Top -@comment node-name, next, previous, up -@unnumbered References - -Margaret A. Ellis, @cite{The Annotated C++ Reference Manual}, -Addison-Wesley, 1990. - -Stanley B. Lippmann, @cite{A C++ Primer}, Addison-Wesley, 1989. - -Bjarne Stroustrup, @cite{The C++ Programming Language}, Addison-Wesley, -1986. - -Sun Microsystems, @cite{Network Programming}, March 1990. - -@c ====================================================================== - -@node Copying, Data Type Index, References, Top -@appendix GNU LIBRARY GENERAL PUBLIC LICENSE -@center Version 2, June 1991 - -@display -Copyright @copyright{} 1991 Free Software Foundation, Inc. -675 Mass Ave, Cambridge, MA 02139, USA -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@unnumberedsec Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -Licenses are intended to guarantee your freedom to share and change -free software---to make sure the software is free for all its users. - - This license, the Library General Public License, applies to some -specially designated Free Software Foundation software, and to any -other libraries whose authors decide to use it. You can use it for -your libraries, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if -you distribute copies of the library, or if you modify it. - - For example, if you distribute copies of the library, whether gratis -or for a fee, you must give the recipients all the rights that we gave -you. You must make sure that they, too, receive or can get the source -code. If you link a program with the library, you must provide -complete object files to the recipients so that they can relink them -with the library, after making changes to the library and recompiling -it. And you must show them these terms so they know their rights. - - Our method of protecting your rights has two steps: (1) copyright -the library, and (2) offer you this license which gives you legal -permission to copy, distribute and/or modify the library. - - Also, for each distributor's protection, we want to make certain -that everyone understands that there is no warranty for this free -library. If the library is modified by someone else and passed on, we -want its recipients to know that what they have is not the original -version, so that any problems introduced by others will not reflect on -the original authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that companies distributing free -software will individually obtain patent licenses, thus in effect -transforming the program into proprietary software. To prevent this, -we have made it clear that any patent must be licensed for everyone's -free use or not licensed at all. - - Most GNU software, including some libraries, is covered by the ordinary -GNU General Public License, which was designed for utility programs. This -license, the GNU Library General Public License, applies to certain -designated libraries. This license is quite different from the ordinary -one; be sure to read it in full, and don't assume that anything in it is -the same as in the ordinary license. - - The reason we have a separate public license for some libraries is that -they blur the distinction we usually make between modifying or adding to a -program and simply using it. Linking a program with a library, without -changing the library, is in some sense simply using the library, and is -analogous to running a utility program or application program. However, in -a textual and legal sense, the linked executable is a combined work, a -derivative of the original library, and the ordinary General Public License -treats it as such. - - Because of this blurred distinction, using the ordinary General -Public License for libraries did not effectively promote software -sharing, because most developers did not use the libraries. We -concluded that weaker conditions might promote sharing better. - - However, unrestricted linking of non-free programs would deprive the -users of those programs of all benefit from the free status of the -libraries themselves. This Library General Public License is intended to -permit developers of non-free programs to use free libraries, while -preserving your freedom as a user of such programs to change the free -libraries that are incorporated in them. (We have not seen how to achieve -this as regards changes in header files, but we have achieved it as regards -changes in the actual functions of the Library.) The hope is that this -will lead to faster development of free libraries. - - The precise terms and conditions for copying, distribution and -modification follow. Pay close attention to the difference between a -``work based on the library'' and a ``work that uses the library''. The -former contains code derived from the library, while the latter only -works together with the library. - - Note that it is possible for a library to be covered by the ordinary -General Public License rather than by this special one. - -@iftex -@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end iftex -@ifinfo -@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end ifinfo - -@enumerate -@item -This License Agreement applies to any software library which -contains a notice placed by the copyright holder or other authorized -party saying it may be distributed under the terms of this Library -General Public License (also called ``this License''). Each licensee is -addressed as ``you''. - - A ``library'' means a collection of software functions and/or data -prepared so as to be conveniently linked with application programs -(which use some of those functions and data) to form executables. - - The ``Library'', below, refers to any such software library or work -which has been distributed under these terms. A ``work based on the -Library'' means either the Library or any derivative work under -copyright law: that is to say, a work containing the Library or a -portion of it, either verbatim or with modifications and/or translated -straightforwardly into another language. (Hereinafter, translation is -included without limitation in the term ``modification''.) - - ``Source code'' for a work means the preferred form of the work for -making modifications to it. For a library, complete source code means -all the source code for all modules it contains, plus any associated -interface definition files, plus the scripts used to control compilation -and installation of the library. - - Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running a program using the Library is not restricted, and output from -such a program is covered only if its contents constitute a work based -on the Library (independent of the use of the Library in a tool for -writing it). Whether that is true depends on what the Library does -and what the program that uses the Library does. - -@item -You may copy and distribute verbatim copies of the Library's -complete source code as you receive it, in any medium, provided that -you conspicuously and appropriately publish on each copy an -appropriate copyright notice and disclaimer of warranty; keep intact -all the notices that refer to this License and to the absence of any -warranty; and distribute a copy of this License along with the -Library. - - You may charge a fee for the physical act of transferring a copy, -and you may at your option offer warranty protection in exchange for a -fee. - -@item -You may modify your copy or copies of the Library or any portion -of it, thus forming a work based on the Library, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - -@enumerate -@item -The modified work must itself be a software library. - -@item -You must cause the files modified to carry prominent notices -stating that you changed the files and the date of any change. - -@item -You must cause the whole of the work to be licensed at no -charge to all third parties under the terms of this License. - -@item -If a facility in the modified Library refers to a function or a -table of data to be supplied by an application program that uses -the facility, other than as an argument passed when the facility -is invoked, then you must make a good faith effort to ensure that, -in the event an application does not supply such function or -table, the facility still operates, and performs whatever part of -its purpose remains meaningful. - -(For example, a function in a library to compute square roots has -a purpose that is entirely well-defined independent of the -application. Therefore, Subsection 2d requires that any -application-supplied function or table used by this function must -be optional: if the application does not supply it, the square -root function must still compute square roots.) -@end enumerate - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Library, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Library, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote -it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Library. - -In addition, mere aggregation of another work not based on the Library -with the Library (or with a work based on the Library) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - -@item -You may opt to apply the terms of the ordinary GNU General Public -License instead of this License to a given copy of the Library. To do -this, you must alter all the notices that refer to this License, so -that they refer to the ordinary GNU General Public License, version 2, -instead of to this License. (If a newer version than version 2 of the -ordinary GNU General Public License has appeared, then you can specify -that version instead if you wish.) Do not make any other change in -these notices. - - Once this change is made in a given copy, it is irreversible for -that copy, so the ordinary GNU General Public License applies to all -subsequent copies and derivative works made from that copy. - - This option is useful when you wish to copy part of the code of -the Library into a program that is not a library. - -@item -You may copy and distribute the Library (or a portion or -derivative of it, under Section 2) in object code or executable form -under the terms of Sections 1 and 2 above provided that you accompany -it with the complete corresponding machine-readable source code, which -must be distributed under the terms of Sections 1 and 2 above on a -medium customarily used for software interchange. - - If distribution of object code is made by offering access to copy -from a designated place, then offering equivalent access to copy the -source code from the same place satisfies the requirement to -distribute the source code, even though third parties are not -compelled to copy the source along with the object code. - -@item -A program that contains no derivative of any portion of the -Library, but is designed to work with the Library by being compiled or -linked with it, is called a ``work that uses the Library''. Such a -work, in isolation, is not a derivative work of the Library, and -therefore falls outside the scope of this License. - - However, linking a ``work that uses the Library'' with the Library -creates an executable that is a derivative of the Library (because it -contains portions of the Library), rather than a ``work that uses the -library''. The executable is therefore covered by this License. -Section 6 states terms for distribution of such executables. - - When a ``work that uses the Library'' uses material from a header file -that is part of the Library, the object code for the work may be a -derivative work of the Library even though the source code is not. -Whether this is true is especially significant if the work can be -linked without the Library, or if the work is itself a library. The -threshold for this to be true is not precisely defined by law. - - If such an object file uses only numerical parameters, data -structure layouts and accessors, and small macros and small inline -functions (ten lines or less in length), then the use of the object -file is unrestricted, regardless of whether it is legally a derivative -work. (Executables containing this object code plus portions of the -Library will still fall under Section 6.) - - Otherwise, if the work is a derivative of the Library, you may -distribute the object code for the work under the terms of Section 6. -Any executables containing that work also fall under Section 6, -whether or not they are linked directly with the Library itself. - -@item -As an exception to the Sections above, you may also compile or -link a ``work that uses the Library'' with the Library to produce a -work containing portions of the Library, and distribute that work -under terms of your choice, provided that the terms permit -modification of the work for the customer's own use and reverse -engineering for debugging such modifications. - - You must give prominent notice with each copy of the work that the -Library is used in it and that the Library and its use are covered by -this License. You must supply a copy of this License. If the work -during execution displays copyright notices, you must include the -copyright notice for the Library among them, as well as a reference -directing the user to the copy of this License. Also, you must do one -of these things: - -@enumerate -@item -Accompany the work with the complete corresponding -machine-readable source code for the Library including whatever -changes were used in the work (which must be distributed under -Sections 1 and 2 above); and, if the work is an executable linked -with the Library, with the complete machine-readable ``work that -uses the Library'', as object code and/or source code, so that the -user can modify the Library and then relink to produce a modified -executable containing the modified Library. (It is understood -that the user who changes the contents of definitions files in the -Library will not necessarily be able to recompile the application -to use the modified definitions.) - -@item -Accompany the work with a written offer, valid for at -least three years, to give the same user the materials -specified in Subsection 6a, above, for a charge no more -than the cost of performing this distribution. - -@item -If distribution of the work is made by offering access to copy -from a designated place, offer equivalent access to copy the above -specified materials from the same place. - -@item -Verify that the user has already received a copy of these -materials or that you have already sent this user a copy. -@end enumerate - - For an executable, the required form of the ``work that uses the -Library'' must include any data and utility programs needed for -reproducing the executable from it. However, as a special exception, -the source code distributed need not include anything that is normally -distributed (in either source or binary form) with the major -components (compiler, kernel, and so on) of the operating system on -which the executable runs, unless that component itself accompanies -the executable. - - It may happen that this requirement contradicts the license -restrictions of other proprietary libraries that do not normally -accompany the operating system. Such a contradiction means you cannot -use both them and the Library together in an executable that you -distribute. - -@item -You may place library facilities that are a work based on the -Library side-by-side in a single library together with other library -facilities not covered by this License, and distribute such a combined -library, provided that the separate distribution of the work based on -the Library and of the other library facilities is otherwise -permitted, and provided that you do these two things: - -@enumerate -@item -Accompany the combined library with a copy of the same work -based on the Library, uncombined with any other library -facilities. This must be distributed under the terms of the -Sections above. - -@item -Give prominent notice with the combined library of the fact -that part of it is a work based on the Library, and explaining -where to find the accompanying uncombined form of the same work. -@end enumerate - -@item -You may not copy, modify, sublicense, link with, or distribute -the Library except as expressly provided under this License. Any -attempt otherwise to copy, modify, sublicense, link with, or -distribute the Library is void, and will automatically terminate your -rights under this License. However, parties who have received copies, -or rights, from you under this License will not have their licenses -terminated so long as such parties remain in full compliance. - -@item -You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Library or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Library (or any work based on the -Library), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Library or works based on it. - -@item -Each time you redistribute the Library (or any work based on the -Library), the recipient automatically receives a license from the -original licensor to copy, distribute, link with or modify the Library -subject to these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - -@item -If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Library at all. For example, if a patent -license would not permit royalty-free redistribution of the Library by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Library. - -If any portion of this section is held invalid or unenforceable under any -particular circumstance, the balance of the section is intended to apply, -and the section as a whole is intended to apply in other circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - -@item -If the distribution and/or use of the Library is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Library under this License may add -an explicit geographical distribution limitation excluding those countries, -so that distribution is permitted only in or among countries not thus -excluded. In such case, this License incorporates the limitation as if -written in the body of this License. - -@item -The Free Software Foundation may publish revised and/or new -versions of the Library General Public License from time to time. -Such new versions will be similar in spirit to the present version, -but may differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Library -specifies a version number of this License which applies to it and -``any later version'', you have the option of following the terms and -conditions either of that version or of any later version published by -the Free Software Foundation. If the Library does not specify a -license version number, you may choose any version ever published by -the Free Software Foundation. - -@item -If you wish to incorporate parts of the Library into other free -programs whose distribution conditions are incompatible with these, -write to the author to ask for permission. For software which is -copyrighted by the Free Software Foundation, write to the Free -Software Foundation; we sometimes make exceptions for this. Our -decision will be guided by the two goals of preserving the free status -of all derivatives of our free software and of promoting the sharing -and reuse of software generally. - -@iftex -@heading NO WARRANTY -@end iftex -@ifinfo -@center NO WARRANTY -@end ifinfo - -@item -BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO -WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. -EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR -OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY -KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE -LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME -THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - -@item -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN -WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY -AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU -FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR -CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE -LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING -RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A -FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF -SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH -DAMAGES. -@end enumerate - -@iftex -@heading END OF TERMS AND CONDITIONS -@end iftex -@ifinfo -@center END OF TERMS AND CONDITIONS -@end ifinfo - -@page -@unnumberedsec How to Apply These Terms to Your New Libraries - - If you develop a new library, and you want it to be of the greatest -possible use to the public, we recommend making it free software that -everyone can redistribute and change. You can do so by permitting -redistribution under these terms (or, alternatively, under the terms of the -ordinary General Public License). - - To apply these terms, attach the following notices to the library. It is -safest to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least the -``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the library's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Library General Public -License as published by the Free Software Foundation; either -version 2 of the License, or (at your option) any later version. - -This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Library General Public License for more details. - -You should have received a copy of the GNU Library General Public -License along with this library; if not, write to the Free -Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a ``copyright disclaimer'' for the library, if -necessary. Here is a sample; alter the names: - -@example -Yoyodyne, Inc., hereby disclaims all copyright interest in the -library `Frob' (a library for tweaking knobs) written by James Random Hacker. - -@var{signature of Ty Coon}, 1 April 1990 -Ty Coon, President of Vice -@end example - -That's all there is to it! - -@c ======================================================================== - -@page -@node Data Type Index, Function Index, Copying, Top -@comment node-name, next, previous, up -@unnumbered Data Type Index - -@printindex tp - -@node Function Index, Concept Index, Data Type Index, Top -@comment node-name, next, previous, up -@unnumbered Function and Method Index - -@printindex fn - -@node Concept Index, , Function Index, Top -@comment node-name, next, previous, up -@unnumbered Concept Index - -@printindex cp - -@contents -@bye |