diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2017-10-26 16:45:12 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2017-10-26 16:45:12 (GMT) |
commit | dd1df8d8538f275b17e0d9d50dca19f4d44595fd (patch) | |
tree | 624bc07023b33668147eaa9097279c6fc92b4e48 /xpa/doc/pod | |
parent | 79d64f400391ce81b4eda73977cb40099256b348 (diff) | |
parent | 6054f36bb658916bd231b9002efb94444e2871c8 (diff) | |
download | blt-dd1df8d8538f275b17e0d9d50dca19f4d44595fd.zip blt-dd1df8d8538f275b17e0d9d50dca19f4d44595fd.tar.gz blt-dd1df8d8538f275b17e0d9d50dca19f4d44595fd.tar.bz2 |
Merge commit '6054f36bb658916bd231b9002efb94444e2871c8' as 'xpa'
Diffstat (limited to 'xpa/doc/pod')
41 files changed, 5405 insertions, 0 deletions
diff --git a/xpa/doc/pod/xpa.pod b/xpa/doc/pod/xpa.pod new file mode 100644 index 0000000..7787d4b --- /dev/null +++ b/xpa/doc/pod/xpa.pod @@ -0,0 +1,399 @@ +=pod + +=head1 NAME + + + +B<XPA: Public Access to Data and Algorithms> + + + +=head1 SYNOPSIS + + + + +This document is the Table of Contents for XPA. + + + +=head1 DESCRIPTION + + + + + +The XPA messaging system provides seamless communication between many +kinds of Unix programs, including X programs and Tcl/Tk programs. It +also provides an easy way for users to communicate with XPA-enabled +programs by executing XPA client commands in the shell or by utilizing +such commands in scripts. Because XPA works both at the programming +level and the shell level, it is a powerful tool for unifying any +analysis environment: users and programmers have great flexibility in +choosing the best level or levels at which to access XPA services, and +client access can be extended or modified easily at any time. + + +A program becomes an XPA-enabled server by defining named points of +public access through which data and commands can be exchanged with +other client programs (and users). Using standard TCP sockets as a +transport mechanism, XPA supports both single-point and broadcast +messaging to and from these servers. It supports direct communication +between clients and servers, or indirect communication via an +intermediate message bus emulation program. Host-based access control +is implemented, as is as the ability to communicate with XPA servers +across a network. + + +XPA implements a layered interface that is designed to be useful both +to software developers and to users. The interface consists of a +library of XPA client and server routines for use in C/C++ programs and +a suite of high-level user programs built on top of these libraries. +Using the XPA library, access points can be added to Tcl/Tk programs, +Xt programs, or to Unix programs that use the XPA event loop or any +event loop based on select(). Client access subroutines can be added +to any Tcl/Tk, Xt, or Unix program. Client access also is supported at +the command line via a suite of high-level programs. + + +Choose from the following topics: + + + +=over 4 + + + + +=item * + +Introduction to XPA +[xpaintro(n)] + + +=item * + +Access Point Names and Templates +[xpatemplate(n)] + + +=item * + +Getting Common Information About Access Points +[xpacommon(n)] + + +=item * + +Communication Methods +[xpamethod(n)] + + +=item * + +Communication Between Hosts +[xpainet(n)] + + +=item * + +Distinguishing Users +[xpausers(n)] + + + +=item * + +XPA User Programs + + +=over 4 + + + + +=item * + +xpaget: get data and info +[xpaget(1)] + + +=item * + +xpaset: send data and info +[xpaset(1)] + + +=item * + +xpainfo: send info alert +[xpainfo(1)] + + +=item * + +xpaaccess: get access point info +[xpaaccess(1)] + + +=item * + +xpamb: message bus emulation +[xpamb(1)] + + +=item * + +xpans: the XPA name server +[xpans(1)] + + +=back + + + + + +=item * + +XPA Server Routines + + +=over 4 + + + + +=item * + +XPANew: define a new access point +[xpanew(3)] + + +=item * + +XPACmdNew: define a new command access point +[xpacmdnew(3)] + + +=item * + +XPACmdAdd: add a command +[xpacmdadd(3)] + + +=item * + +XPACmdDel: delete a command +[xpacmddel(3)] + + +=item * + +XPAInfoNew: define an info access point +[xpainfonew(3)] + + +=item * + +XPAFree: free an access point +[xpafree(3)] + + +=item * + +XPAMainLoop: event loop for select server +[xpamainloop(3)] + + +=item * + +XPAPoll: poll for XPA events +[xpapoll(3)] + + +=item * + +XPACleanup: release reserved XPA memory +[xpacleanup(3)] + + +=item * + +XPA Server Macros: accessing structure internals +[xpamacros(3)] + + +=item * + +XPA Race Conditions: how to avoid them +[xparace(3)] + + +=item * + +XPA Out of Memory (OOM) errors +[xpaoom(3)] + + +=back + + + + + +=item * + +XPA Client Routines + + +=over 4 + + + + +=item * + +XPAOpen: open a persistent client connection +[xpaopen(3)] + + +=item * + +XPAClose: close persistent client connection +[xpaclose(3)] + + +=item * + +XPAGet: get data +[xpaget(3)] + + +=item * + +XPASet: send data or commands +[xpaset(3)] + + +=item * + +XPAInfo: send an info alert +[xpainfo(3)] + + +=item * + +XPAGetFd: get data and write to an fd +[xpagetfd(3)] + + +=item * + +XPASetFd: read data from and fd and send +[xpasetfd(3)] + + +=item * + +XPANSLookup: look up an access point +[xpanslookup(3)] + + +=item * + +XPAAccess: get access info +[xpaaccess(3)] + + +=item * + +The XPA/Xt Interface: Xt interface to XPA +[xpaxt(n)] + + +=item * + +The XPA/Tcl Interface: Tcl interface to XPA +[xpatcl(n)] + + +=back + + + + + +=item * + +Tailoring the XPA Environment + + +=over 4 + + + + +=item * + +Environment Variables +[xpaenv(n)] + + +=item * + +Access Control +[xpaacl(n)] + + +=back + + + + + +=item * + +Miscellaneous + + +=over 4 + + + + + +=item * + +Where to Find Example/Test Code + + +=item * + +User Changes Between XPA 1.0 and 2.0 + + +=item * + +API Changes Between XPA 1.0 and 2.0 + + +=item * + +What Does XPA Stand For, Anyway? + + +=back + + + + + +=back + + + + + + +=cut diff --git a/xpa/doc/pod/xpaaccess.pod b/xpa/doc/pod/xpaaccess.pod new file mode 100644 index 0000000..ab34b9b --- /dev/null +++ b/xpa/doc/pod/xpaaccess.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + + + +B<xpaaccess: see if template matches registered XPA access points> + + + +=head1 SYNOPSIS + + + + + +xpaaccess [-c] [-h] [-i nsinet] [-m method] [-n] [-t sval,lval] [-u users] -v <template> [type] + + + + + +=head1 OPTIONS + + + + + + -c contact each access point individually + -h print help message + -i access XPA point on different machine (override XPA_NSINET) + -m override XPA_METHOD environment variable + -n return number of matches instead of "yes" or "no" + -t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) + -u [users] XPA points can be from specified users (override XPA_NSUSERS) + -v print info about each successful access point + -V print info or error about each access point + --version display version and exit + + + + +=head1 DESCRIPTION + + + + +xpaaccess returns "yes" to stdout (with a return error code if 1) if there are +existing XPA access points that match the +template +(and optional access type: g,i,s). Otherwise, it returns "no" (with a +return error code of 0). If -n is specified, the number of matches is +returned instead (both to stdout and in the returned error code). If +-v is specified, each access point is displayed to stdout instead of +the number of matches. + + +By default, xpaaccess simply contacts the xpans name server to find +the list of registered access points that match the specified +template. It also checks to make sure the specified types are +supported by that access point. This is the fastest way to determine +available access points. However, an access point might registered but +not yet available, if, for example, the server program has not entered +its event loop to process XPA requests. To find access points that are +guaranteed to be available for processing, use the -c (contact) +switch. With this switch, xpaaccess contacts each matching XPA server +(rather than the name server) to make sure the registered access point +really is ready for processing. In this mode, if an access point is +registered but not available, xpaaccess will pause for a period of +time equal to the XPA_LONG_TIMEOUT, in order to give the server a +chance to ready itself. By default, this timeout is 30 seconds. You +can shorten the time of delay using the -t "short,long" switch. For +example, to shorten the delay time to 2 seconds, use: + + xpaaccess -c -t "2,2" ds9 + +The first argument is the short delay value, and is ignored in this +operation. The second is the long delay timeout. + + +Note also that the default xpaaccess method (no -c switch) does not +check access control (acls) but rather only checks whether the access +point is both registered with the xpans name server and provides the +specified type of access. In other words, the default xpaaccess could +return 'yes' when you might not actually have access. This mode also +always returns 'yes' for the xpans name server itself, regardless of +whether the name server is active. The -c (contact) switch, which +contacts the access point directly, can and does check the access +control (only for servers using version 2.1 and above) and also +returns the real status of xpans. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpaacl.pod b/xpa/doc/pod/xpaacl.pod new file mode 100644 index 0000000..3be9d4c --- /dev/null +++ b/xpa/doc/pod/xpaacl.pod @@ -0,0 +1,145 @@ +=pod + +=head1 NAME + + + +B<XPAAcl: Access Control for XPA Messaging> + + + +=head1 SYNOPSIS + + + + + +XPA supports host-based access control for each XPA access point. You +can enable/disable access control using the XPA_ACL environment +variable. You can specify access to specific XPA access points for +specific machines using the XPA_DEFACL and XPA_ACLFILE environment +variables. By default, an XPA access point is accessible only to +processes running on the same machine (same as X Windows). + + + +=head1 DESCRIPTION + + + + + +When INET sockets are in use (the default, as specified by the +I<XPA_METHOD> environment variable), XPA supports a host-based +access control mechanism for individual access points. This mean that +access can be specified for get, set, or info operations for each +access point on a machine by machine basis. For LOCAL sockets, access +is restricted (by definition) to the host machine. + + +XPA access control is enabled by default, but can be turned off by +setting the I<XPA_ACL> environment variable to I<false>. +In this case, any process can access any XPA server. + + +Assuming that access control is turned on, the ACL for an individual +XPA access point is set up when that access point is registered +(although it can be changed later on; see below). This can be done in +one of two ways: + +Firstly, the I<XPA_ACLFILE> environment variable can defined to +point to a file of access controls for individual access points. The format +of this file is: + + class:name ip acl + +The first argument is a template that specifies the class:name of the +access point covered by this ACL. See +XPA Access Points and Templates +for more information about xpa templates. + + +The second argument is the IP address (in human-readable format) of +the machine which is being given access. This argument can be +I<*> to match all IP addresses. It also can be I<$host> +to match the IP address of the current host. + + +The third argument is a string combination of I<s>, I<g>, +or I<i> to allow I<xpaset>, I<xpaget>, or +I<xpainfo> access respectively. The ACL argument can be +I<+> to give I<sgi> access or it can be I<-> to turn +off all access. + + +For example, + + *:xpa1 somehost sg + *:xpa1 myhost + + * * g + +will allow processes on the machine somehost to make xpaget and xpaset calls, +allow processes on myhost to make any call, and allow all other hosts to +make xpaget (but not xpaset) calls. + +Secondly, if the I<XPA_ACLFILE> does not exist, then a single +default value for all access points can be specified using the +I<XPA_DEFACL> environment variable. The default value for this +variable is: + + #define XPA_DEFACL "*:* $host +" + +meaning that all access points are fully accessible to all processes +on the current host. Thus, in the absence of any ACL environment variables, +processes on the current host have full access to all access points +created on that host. This parallels the X11 xhost mechanism. + + +Access to an individual XPA access point can be changed using the -acl +parameter for that access point. For example: + + xpaset -p xpa1 -acl "somehost -" + +will turn off all access control for somehost to the xpa1 access point, while: + + xpaset -p XPA:xpa1 -acl "beberly gs" + +will give beberly xpaget and xpaset access to the access point whose +class is XPA and whose name is xpa1. + +Similarly, the current ACL for a given access point can be retrieved using: + + xpaget xpa1 -acl + +Of course, you must have xpaget access to this XPA access point to +retrieve its ACL. + + +Note that the XPA access points registered in the I<xpans> +program also behave according to the ACL rules. That is, you cannot +use xpaget to view the access points registered with xpans unless +you have the proper ACL. + + +Note also when a client request is made to an XPA server, the access +control is checked when the initial connection is established. This +access in effect at this time remains in effect so long as the client +connection is maintained, regardless of whether the access fro that +XPA is changed later on. + + +We recognize that host-based access control is only relatively secure +and will consider more stringent security (e.g., private key) in the +future if the community requires such support. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpaatexit.pod b/xpa/doc/pod/xpaatexit.pod new file mode 100644 index 0000000..4310835 --- /dev/null +++ b/xpa/doc/pod/xpaatexit.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + + + +B<XPAAtExit: install exit handler> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + void XPAAtExit(void); + + + + + +=head1 DESCRIPTION + + + + +XPAAtExit() will install an exit handler using atexit() to run XPAFree on all +XPA access points. This might be useful in cases where Unix sockets are being +used: if an explicit call to XPAFree() is not made by the program, the Unix +socket file will not be deleted immediately without an atexit handler. (NB: this +call should not be made in a Tcl/Tk application. Accessing the Tcl native file +system after Tcl has shut down all file systems causes the Tcl/Tl program to +crash). + + + + +=cut diff --git a/xpa/doc/pod/xpachanges.pod b/xpa/doc/pod/xpachanges.pod new file mode 100644 index 0000000..bce7be0 --- /dev/null +++ b/xpa/doc/pod/xpachanges.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + + + +B<XPA Changes: Changes For Users from XPA 1.0 and 2.0> + + + +=head1 SYNOPSIS + + + + + +This document describes changes that will affect users who migrate +from XPA 1.0 to XPA 2.0. + + + +=head1 DESCRIPTION + + + + + +There have been a few changes that affect users who upgrade XPA +from version 1.0 to version 2.0. These changes are detailed below. + + +=over 4 + + + + + +=item * + +XPA commands no longer have a resolver routine (this is open to +negotiations, but we decided the idea was dumb). For the SAOtng +program, this means that you must explicitly specify the access +point, i.e.,: + + cat foo.fits | xpaset SAOtng fits + + + +instead of: + + cat foo.fits | xpaset SAOtng + + + + +=item * + +By default, xpaset, xpaget, etc. now wait for the server callback to +complete; i.e., the old -W is implied (and the switch is ignored). +This allows support for better error handling. If you want xpaset, etc. +to return before the callback is complete, use -n switch: + + echo "file foo.fits" | xpaset -n SAOtng + + + + +=item * + +The old -w switch in xpaset and xpaget is no longer necessary (and is +ignored), since you can have more than one process communicating with +an xpa access point at one time. + + + + +=item * + +The new -p switch on xpaset means you need not read from stdout: + + xpaset -p SAOtng colormap I8 + + +will send the paramlist to the SAOtng callback without reading from stdin. + + + +=back + + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpacleanup.pod b/xpa/doc/pod/xpacleanup.pod new file mode 100644 index 0000000..2d55e5a --- /dev/null +++ b/xpa/doc/pod/xpacleanup.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + + + +B<XPACleanup: release reserved XPA memory> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + void XPACleanup(void); + + + + + +=head1 DESCRIPTION + + + + +When XPA is initialized, it allocates a small amount of memory for the +access control list, temp directory path, and reserved commands. This +memory is found by valgrind to be "still reachable", meaning that "your +program didn't free some memory it could have". Calling the +XPACleanup() routine before exiting the program will free this memory +and make valgrind happy. + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpaclient.pod b/xpa/doc/pod/xpaclient.pod new file mode 100644 index 0000000..858a8a8 --- /dev/null +++ b/xpa/doc/pod/xpaclient.pod @@ -0,0 +1,95 @@ +=pod + +=head1 NAME + + + +B<XPAClient: The XPA Client-side Programming Interface> + + + +=head1 SYNOPSIS + + + + +A description of the XPA client-side programming interface. + + + +=head1 DESCRIPTION + + + +B<Introduction to XPA Client Programming> + +Sending/receiving data to/from an XPA access point is easy: you +generally only need to call the XPAGet() or XPASet() subroutines. + + #include <xpa.h> + + int XPAGet(XPA xpa, + char *template, char *paramlist, char *mode, + char **bufs, size_t *lens, char **names, char **messages, int n); + + int XPASet(XPA xpa, + char *template, char *paramlist, char *mode, + char *buf, size_t len, char **names, char **messages, int n); + + int XPAInfo(XPA xpa, + char *template, char *paramlist, char *mode, + char **names, char **messages, int n); + + int XPAAccess(XPA xpa, + char *template, char *paramlist, char *mode, + char **names, char **messages, int n); + + int XPAGetFd(XPA xpa, + char *template, char *paramlist, char *mode, + int *fds, char **names, char **messages, int n); + + int XPASetFd(XPA xpa, + char *template, char *paramlist, char *mode, + int fd, char **names, char **messages, int n); + + XPA XPAOpen(char *mode); + + void XPAClose(XPA xpa); + + int XPANSLookup(XPA xpa, + char *template, char *type, + char ***classes, char ***names, char ***methods, char ***infos); + + +B<Introduction> + +To use the XPA application programming interface, a software developer +generally will include the xpa.h definitions file: + + #include <xpa.h> + +in the software module that defines or accesses an XPA access point and +then will link against the libxpa.a library: + + gcc -o foo foo.c libxpa.a + +XPA has been compiled using both C and C++ compilers. + +Client communication with XPA public access points generally is +accomplished using XPAGet() or XPASet() within a program (or xpaget +and xpaset at the command line). Both routines require specification +of the name of the access point. If a template +is used to specify the access point name (e.g., "ds9*"), then +communication will take place with all servers matching that template. + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpaclose.pod b/xpa/doc/pod/xpaclose.pod new file mode 100644 index 0000000..7148752 --- /dev/null +++ b/xpa/doc/pod/xpaclose.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + + + +B<XPAClose: close a persistent XPA client handle> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + void XPAClose(XPA xpa); + + + + + +=head1 DESCRIPTION + + + + +XPAClose closes the persistent connections associated with this XPA struct +and frees all allocated space. It also closes the open sockets connections +to all XPA servers that were opened using this handle. + + +B<Example:> + + #include <xpa.h> + + XPA xpa; + XPAClose(xpa); + + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpacmdadd.pod b/xpa/doc/pod/xpacmdadd.pod new file mode 100644 index 0000000..31859e5 --- /dev/null +++ b/xpa/doc/pod/xpacmdadd.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + + + +B<XPACmdAdd: add a command to an XPA command public access point> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + XPACmd XPACmdAdd(XPA xpa, char *name, char *help, + int (*send_callback)(), + void *send_data, char *send_mode, + int (*rec_callback)(), + void *rec_data, char *rec_mode); + + + + + +=head1 DESCRIPTION + + + + +Add a command to an XPA command access point. The XPA argument specifies the +XPA struct returned by a call to XPANewCmd(). The name argument is the +name of the command. The other arguments function identically to the +arguments in the XPANew() command, i.e., the send_callback and rec_callback +routines have identical calling sequences to their XPANew() counterparts, +with the exceptions noted below. + + +When help is requested for a command access point using: + + xpaget -h class:name + + +all of the command help strings are listed. To get help for a given +command, use: + + xpaget -h class:name cmd + + +Also, the acl keyword in the send_mode and receive_mode strings is +global to the access point, not local to the command. Thus, the value +for the acl mode should be the same in all send_mode (or receive_mode) +strings for each command in a command access point. (The acl for +send_mode need not be the same as the acl for receive_mode, though). + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpacmddel.pod b/xpa/doc/pod/xpacmddel.pod new file mode 100644 index 0000000..95c545d --- /dev/null +++ b/xpa/doc/pod/xpacmddel.pod @@ -0,0 +1,43 @@ +=pod + +=head1 NAME + + + +B<XPACmdDel: remove a command from an XPA command public access point> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + void XPACmdDel(XPA xpa, XPACmd cmd); + + + + + +=head1 DESCRIPTION + + + + +This routine removes a command from the list of available commands in +a given XPA. That command will no longer be available for processing. + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpacmdnew.pod b/xpa/doc/pod/xpacmdnew.pod new file mode 100644 index 0000000..429972b --- /dev/null +++ b/xpa/doc/pod/xpacmdnew.pod @@ -0,0 +1,90 @@ +=pod + +=head1 NAME + + + +B<XPACmdNew: create a new XPA public access point for commands> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + XPA XPACmdNew(char *class, char *name); + + + + + +=head1 DESCRIPTION + + + + +Create a new XPA public access point for commands that will share a +common identifier class:name. Enter this access point into the XPA +name server, so that it can be accessed by external processes. +XPACmdNew() returns an XPA struct. + + +It often is more convenient to have one public access point that can +manage a number of commands, rather than having individual access +points for each command. For example, it is easier to command the +ds9 image display using: + + echo "colormap I8" | xpaset ds9 + echo "scale log" | xpaset ds9 + echo "file foo.fits" | xpaset ds9 + + +then to use: + + echo "I8" | xpaset ds9_colormap + echo "log" | xpaset ds9_scale + echo "foo.fits" | xpaset ds9_file + + +In the first case, the commands remain the same regardless of the +target XPA name. In the second case, the command names must change +for each instance of ds9. That is, if a second instance of ds9 +called DS9 were running, it would be commanded either as: + + echo "colormap I8" | xpaset DS9 + echo "scale log" | xpaset DS9 + echo "file foo.fits" | xpaset DS9 + + +or as: + + echo "I8" | xpaset DS9_colormap + echo "log" | xpaset DS9_scale + echo "foo.fits" | xpaset DS9_file + + +Thus, in cases where a program is going to manage many commands, it +generally is easier to define them as commands associated with the +XPACmdNew() routine, rather than as separate access points using +XPANew(). + + +When XPACmdNew() is called, only the class:name identifier is +specified. Each sub-command is subsequently defined using the +XPACmdAdd() routine. + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpacode.pod b/xpa/doc/pod/xpacode.pod new file mode 100644 index 0000000..c5ea647 --- /dev/null +++ b/xpa/doc/pod/xpacode.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + + + +B<XPACode: Where to Find Example/Test Code> + + + +=head1 SYNOPSIS + + + + + +The XPA source code directory contains two test programs, +I<stest.c>, and I<ctest.c> that can serve as +examples for writing XPA servers and clients, respectively. +They also can be used to test various features of XPA. + + + +=head1 DESCRIPTION + + + + + +To build the XPA test programs, execute: + + make All + +in the XPA source directory to generate the I<stest> and +I<ctest> programs. (NB: this should work on all platforms, +although we have had problems with unresolved externals on one +Sun/Solaris machine, for reasons still unknown.) + +The stest program can be executed with no arguments to start +an XPA server that contains the access points: xpa, xpa1, +c_xpa (containing sub-commands cmd1 and cmd2), and i_xpa. +You then can use xpaset and xpaget to interact with these access points: + + cat xpa.c | xpaset xpa # send to xpa + cat xpa.c | xpaset "xpa*" # send to xpa and xpa1 + xpaget xpa # receive from xpa + xpaget xpa* # receive from xpa and xpa1 + +etc. You also can use ctest to do the same thing, or to iterate: + + ctest -s -l 100 xpa # send to xpa 100 times + ctest -s -l 100 "xpa*" # send to xpa and xpa1 100 times + ctest -g -l 100 xpa # receive from xpa 100 times + ctest -g -l 100 "xpa*" # receive from xpa and xpa1 100 times + +More options are available: see the stest.c and ctest.c code itself, which +were used extensively to debug XPA. + + +The file test.tcl in the XPA source directory gives examples for using the +XPATclInterface. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpacommon.pod b/xpa/doc/pod/xpacommon.pod new file mode 100644 index 0000000..9fc9746 --- /dev/null +++ b/xpa/doc/pod/xpacommon.pod @@ -0,0 +1,266 @@ +=pod + +=head1 NAME + + + +B<XPACommon: Getting Common Information About Access Points> + + + +=head1 SYNOPSIS + + + + + +There are various kinds of generic information you can retrieve about +an XPA access point by using the xpaget command. + + + +=head1 DESCRIPTION + + + + + +You can find out which XPA access points have been registered with +the currently running +XPA name server +by executing the +xpaget +command to retrieve info from the XPA name server: + + xpaget xpans + +If, for example, the +stest test server program +is running, the following XPA access points will be returned (the specifics +of the returned info will vary for different machines and users): + + XPA xpa gs 838e2f67:1262 eric + XPA xpa1 gs 838e2f67:1266 eric + XPA c_xpa gs 838e2f67:1267 eric + XPA i_xpa i 838e2f67:1268 eric + +Note that access to this information is subject to the usual +XPA Access Control restrictions. + + +Each XPA access point supports a number of reserved sub-commands that provide +access to different kinds of information, e.g. the access control for +that access point. These sub-commands can be executed by using +xpaset +or +xpaget +at the command line, or +XPAGet() +or +XPASet() +in programs, e.g: + + xpaget ds9 -acl + xpaget ds9 -help + xpaget ds9 env FOO + + xpaset -p ds9 env FOO foofoo + +With the exception of B<-help> and B<-version>, reserved +sub-commands are available only on the machine on which the XPA server +itself is running. + +The following reserved sub-commands are defined for all access points: + + +=over 4 + + + + + + +=item * + +B<-acl> get (set) the access control list [options: host type acl, for set] + + +The 'xpaset' option allows you to add a new acl for a given host, or change +the acl for an existing host. See +XPA Access Control +for more information. +This access point is available only on the server machine. + + + + +=item * + +B<-env> get (set) an environment variable [options: name (value, for set)] + + +The 'xpaget' option will return the value of the named environment +variable. The 'xpaset' option will set the value of the names +variable to the specified value. +This access point is available only on the server machine. +(Please be advised that we have had problems setting environment +variables in static Tcl/Tk programs such as ds9 running under Linux.) + + + + +=item * + +B<-clipboard> set(get) information on a named clipboard + + +Clients can store ASCII state information on any number of named +clipboards. Clipboards of the same name created by clients on +different machines are kept separate. The syntax for creating a +clipboard is: + + [data] | xpaset [server] -clipboard add|append [clipboard_name] + xpaset -p [server] -clipboard delete [clipboard_name] + +Use "add" to create a new clipboard or replace the contents of an existing +one. Use "append" to append to an existing clipboard. + +Information on a named clipboard is retrieved using: + + xpaget [server] -clipboard [clipboard_name] + + + + +=item * + +B<-exec> set: execute commands from buffer [options: none] + + +If -exec is specified in the paramlist of an 'xpaset' call, then further +sub-commands will be retrieved from the data buffer. + + + + +=item * + +B<-help> get: return help string for this XPA or sub-command [options: name (for sub-commands)] + + +Each XPA access point and each XPA sub-command can have a help string +associated with it that is specified when the access point is defined. +The -help option will return this help string. For XPA access points +that contain user-defined sub-commands, you can get the help string +for a particular sub-command by specifying its name, or else get the +help strings for all sub-commands if not name is specified. + + + + +=item * + +B<-ltimeout> get (set) the long timeout value [options: seconds|reset] + + +The 'xpaget' option will return the value of the long timeout (in seconds). +The 'xpaset' option will set the value of the long timeout. If "reset" is +specified, then the timeout value will be reset to the default value. + + + + +=item * + +B<-nsconnect> set: re-establish name server connection to all XPA's [options: none] + + +If the +XPA Name Server (xpans) +process has terminated unexpectedly and then re-started, this +sub-command can be used to re-establish the connection. You use it by +sending the command to the [name:port] or [file] of the access point +instead of to the XPA name (since the latter requires the xpans +connection!): + + xpaset -p 838e2f67:1268 -nsconnect + +See xpans for more information. + + + + +=item * + +B<-nsdisconnect> set: break name server connection to all XPA's [options: none] + + +This sub-command will terminate the connection to the +XPA Name Server (xpans), thereby making +all access points inaccessible except through their underlying [name:port] +or [file] identifiers. I forget why we added it, it seems pretty useless. + + + + +=item * + +B<-stimeout> get (set) the short timeout value [options: seconds|reset] + + +The 'xpaget' option will return the value of the short timeout (in seconds). +The 'xpaset' option will set the value of the short timeout. If "reset" is +specified, then the timeout value will be reset to the default value. + + + + +=item * + +B<-remote> set: register xpa with remote server [options: host[:port] [acl]] [-proxy] + + +This sub-command will register the XPA access point with the XPA name +server (xpans) on the specified host (which must already be running). +The specified host also is given access control to the access point, +using the specified acl or the default acl of "+" (meaning the remote +host can xpaset, xpaget, xpainfo or xpaaccess). If the acl is +specified as "-", then the access point is unregistered. +See Communication Between Machines +for more information on how this sub-command is used. + + + + +=item * + +B<-version> get: return XPA version string [options: none] + + +The version refers to the version of XPA used to define this access point +(currently something like 2.0). + + + +=back + + + + +You can add your own reserved commands to all XPA access points by using the +XPACmdAdd() +routine, passing the XPA handle returned by I<XPA XPAGetReserved(void)> +as the first argument. Note again that these will only be available on the +machine where the XPA service is running. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpaconvert.pod b/xpa/doc/pod/xpaconvert.pod new file mode 100644 index 0000000..75597a7 --- /dev/null +++ b/xpa/doc/pod/xpaconvert.pod @@ -0,0 +1,202 @@ +=pod + +=head1 NAME + + + +B<XPAConvert: Converting the XPA API to 2.0> + + + +=head1 SYNOPSIS + + + + + +This document describes tips for converting from xpa 1.0 (Xt-based +xpa) to xpa 2.0 (socket-based xpa). + + + +=head1 DESCRIPTION + + + + + +The following are tips for converting from xpa 1.0 (Xt-based xpa) to +xpa 2.0 (socket-based xpa). The changes are straight-forward and +almost can be done automatically (we used editor macros for most of +the conversion). + + +=over 4 + + + + + +=item * + +The existence of the cpp XPA_VERSION directive to distinguish between 1.0 +(where it is not defined) and 2.0 (where it is defined). + + + + +=item * + +Remove the first widget argument from all send and receive server +callbacks. Also change first 2 arguments from XtPointer to void +*. For example: + +#ifdef XPA_VERSION +static void XPAReceiveFile(client_data, call_data, paramlist, buf, len) + void *client_data; + void *call_data; + char *paramlist; + char *buf; + int len; +#else +static void XPAReceiveFile(w, client_data, call_data, paramlist, buf, len) + Widget w; + XtPointer client_data; + XtPointer call_data; + char *paramlist; + char *buf; + int len; +#endif + + + + +=item * + +Server callbacks should be declared as returning int instead +of void. They now should return 0 for no errors, -1 for error. + + + + +=item * + +The mode flags have changed when defining XPA server callbacks. +The old I<S> flag (save buffer) is replaced by I<freebuf=false>. +The old I<E> flag (empty buffer is OK) is no longer used (it +was an artifact of the X implementation). + + + + +=item * + +Change NewXPACommand() to XPAcmdNew(), with the new calling sequence: + + xpa = NewXPACommand(toplevel, NULL, prefix, NULL); + +is changed to: + + xpa = XPACmdNew(xclass, name); + + + + +=item * + +Change the AddXPACommand() subroutine name to XPACmdAdd (with the same +calling sequence): + + AddXPACommand(xpa, "file", + "\tdisplay a new file\n\t\t requires: filename", + NULL, NULL, NULL, XPAReceiveFile, text, NULL); + +is changed to: + + XPACmdAdd(xpa, "file", + "\tdisplay a new file\n\t\t requires: filename", + NULL, NULL, NULL, XPAReceiveFile, text, NULL); + + + + +=item * + +The XPAXtAppInput() routine should be called just before XtAppMainLoop() +to add xpa fds to the Xt event loop: + + /* add the xpas to the Xt loop */ + XPAXtAddInput(app, NULL); + + /* process events */ + XtAppMainLoop(app); + + + + +=item * + +Change NewXPA() to XPANew() and call XPAXtAddInput() if the XtAppMainLoop +routine already has been entered: + + xpa = NewXPA(saotng->xim->toplevel, prefix, xparoot, + "FITS data or image filename\n\t\t options: file type", + XPASendData, new, NULL, + XPAReceiveData, new, "SE"); + +is changed to: + + sprintf(tbuf, "%s.%s", prefix, xparoot); + xpa = XPANew("SAOTNG", tbuf, + "FITS data or image filename\n\t\t options: file type", + XPASendData, new, NULL, + XPAReceiveData, new, "SE"); + XPAXtAddInput(XtWidgetToApplicationContext(saotng->xim->toplevel), xpa); + + + + +=item * + +Change XPAInternalReceiveCommand() to XPACmdInternalReceive() +remove first argument in the calling sequence): + + XPAInternalReceiveCommand(im->saotng->xim->toplevel, + im->saotng, im->saotng->commands, + "zoom reset", NULL, 0); + +is changed to: + + XPACmdInternalReceive(im->saotng, im->saotng->commands, + "zoom reset", NULL, 0); + + + + +=item * + +Change DestroyXPA to XPAFree: + + DestroyXPA(im->dataxpa); + +is changed to: + + XPAFree(im->dataxpa); + + + +=back + + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpaenv.pod b/xpa/doc/pod/xpaenv.pod new file mode 100644 index 0000000..a1d095f --- /dev/null +++ b/xpa/doc/pod/xpaenv.pod @@ -0,0 +1,517 @@ +=pod + +=head1 NAME + + + +B<XPAEnv: Environment Variables for XPA Messaging> + + + +=head1 SYNOPSIS + + + + +Describes the environment variables which can be used to tailor the overall +XPA environment. + + + +=head1 DESCRIPTION + + + + + +The following environment variables are supported by XPA: + + +=over 4 + + + + + +=item * + +B<XPA_ACL> + + +If I<XPA_ACL> is I<true>, then +host-based XPA Access Control +is turned on and only specified machines can access specified access +points. If I<false>, then access control is turned off and any +machine can access point. The default is turn turn access control on. + + + + +=item * + +B<XPA_ACLFILE> + + +If +XPA Access Control +is turned on, this variable specifies the name of the file containing +access control information for all access points started by this user. +The default file name is: I<$HOME/acls.xpa>. + + + + +=item * + +B<XPA_CONNECT_TIMEOUT> + + +When an XPA server first starts up, it immediately tries to +connect to the XPA name server program (xpans) on the host specified by +the I<XPA_NSINET> variable. (If this connection fails on the +local host, and if xpans can be found in the path, then the name +server is started automatically.) Unfortunately, a mis-configured +network can cause this connect attempt to hang for many seconds while +the connect() system call times out. Therefore, an alarm is started +to interrupt the connect() call and prevent a long hang. The initial +value of the alarm timeout is 10 seconds, but can be changed by setting +this environment variable. If you want to disable the alarm and allow +the initial connect() to time out, set the value of this variable to +0. Normally, users would not change this variable at all. + + + + +=item * + +B<XPA_CLIENT_DOXPA> + + +Normally, an XPA client (xpaget, xpaset, etc.) will process incoming +XPA server requests while awaiting the completion of the client request. +Setting this variable to "false" will prevent XPA server requests from +being processed by the client. + + + + +=item * + +B<XPA_DEFACL> + + +If +XPA Access Control +is turned on, this variable specifies the default access control +condition for all access points, if the I<XPA_ACLFILE> file does +not exist. The default acl is: I<$host:* $host +>, meaning that +all processes on the host machine have full access to all access points. + + + + +=item * + +B<XPA_HOST> + + +For the INET socket method, XPA utilizes the canonical hostname (as +returned by the gethostname() routine) to construct the IP part of the +method id. Under some circumstances, this might not be a correct choice +of name and IP. For example, if an XPA server is started on a machine +running VPN, you might want to use the VPN name and IP instead of the +canonical host name, so that other machines in the VPN network can +access the server. In this case, you can set the XPA_HOST to be +the VPN name (if resolvable) or, more easily, the VPN IP. + + + + +=item * + +B<XPA_IOCALLSXPA> + + +Setting this variable causes all XPA socket IO calls to process +outstanding XPA requests whenever the primary socket is not ready for +IO. This means that a server making a client call will (recursively) +process incoming server requests while waiting for client completion. +This inter-IO XPA processing avoids a rare +XPA Race Condition: two or more +XPA servers sending messages to one another using an XPA client +routine such as XPASet() can deadlock while each waits for the other +server to respond. This can happen, for example, if the servers call +XPAPoll() with a time limit, and send messages in between the polling call. + + +By default, this option is turned off, because we judge that the added +code complication and overhead involved will not be justified by the +amount of its use. Moreover, processing XPA requests within socket IO +can lead to non-intuitive results, since incoming server requests will +not necessarily be processed to completion in the order in which they +are received. + + + + +=item * + +B<XPA_LOGNAME> + + +XPA preferentially uses the de facto standard environment variable +LOGNAME to determine the username when registering an access point in +the name server. If this environment variable has been used for +something other than the actual user name (such as a log file name), +unexpected results can ensue. In such cases, use the XPA_LOGNAME +variable to set the user name. (If neither exists, then getpwuid(geteuid()) +is used as a last resort). + + + + +=item * + +B<XPA_LONG_TIMEOUT> + + +XPA is designed to allow data to be sent from one process to +another over a long period of time (i.e., a program that generates +image data sends that data to an image display, but slowly) but it +also seeks to prevent hangs. This is done by supporting 2 timeout +periods: a I<short> timeout for protocol communication +and a I<long> for data communication. + +The I<XPA_LONG_TIMEOUT> variable controls the I<long> +timeout and is used to prevent hangs in cases where communication +between the client and server that is I<not> controlled by the +XPA interface itself. Transfer of data between client and server, or a +client's wait for a status message after completion of the server +callback, are two examples of this sort of communication. By default, +the I<long> timeout is set to 180 seconds. +Setting the value to -1 will disable I<long> timeouts and allow +an infinite amount of time. + + + + +=item * + +B<XPA_MAXHOSTS> + + +The maximum number of access points that the programs +I<xpaset>, I<xpaget>, and I<xpainfo> will +communicate with at one time. The default is 64, meaning, for +example, that the I<xpaset> program will not send a message +to more than 100 access points at one time and I<xpaget> will +not retrieve from more than 100 access points at one time. + + + + +=item * + +B<XPA_METHOD> + + +Determines the socket connection method used by this session of XPA. +The choices are: I<inet> (to use INET or Internet-based +sockets), I<localhost> (to use the machines localhost inet +socket), or I<local (unix)> (to use UNIX sockets). The default +is I<INET>. Using the I<inet> method will allow access +from other machines (subject to access controls) but using +I<localhost> or I<local> will not. Localhost is most useful +for private access and when the machine in question is not connected +to the Internet. The unix method also can be used for private access +and non-Internet connections (Unix platforms only). + +Once defined, the first registration of an XPA access point will +ensure that an instance of the +XPA Name Server (xpans) +is running that handles that connection method. All new access points +will use the new connection method but existing access points will use +the original method. + + + + +=item * + +B<XPA_NSINET> + + +For the I<inet> method of socket connection, this variable +specifies the host and port on which the +XPA Name Server (xpans) +is listens for new access points. The default is I<$host:$port>, +meaning that the default XPA port (14285) on the current machine +(as returned by gethostname()) is used. If several machines were all +accessing the same XPA access points, you would use this variable to +specify that they all use the same name server to find out about these +access points. For example, a value of I<myhost:$port> would +mean that the xpans name server is running on myhost and uses the +default port 12345. All machines would then get the XPA access points +registered with that name server, subject to access controls. + +The port used by xpans to register its XPA access point normally is +taken to be one greater than the port on which it receives new access +points from XPA servers. You can specify a specific access point port +using the syntax machine:port1,port2, i.e., the access point port is +specified after the comma. For example, $host:12345,23456 will listen +for new access ports on 12345 and will accept XPA commands on 23456. + + + + +=item * + +B<XPA_NSREGISTER> + + +This boolean variable specifies whether a server registers its XPA +access point with the specified xpans name server. The default is +I<true>. If set to I<false>, the access point still is +set up but it is not registered with xpans and therefore cannot be +accessed by name. (It can be accessed by method, if the latter is +known.) Note that an access point can be registered later on (using +-remote or -proxy, for example). This variable mainly is useful in +cases where the Internet configuration is broken (so that registration +causes a DNS hang) but you still wish to and can use the server with a +remote xpans (e.g., ds9's Virtual Observatory capability). + + + + +=item * + +B<XPA_NSUNIX> + + +For the I<local> method of socket connection, this variable +specifies the name of the Unix file that will be used to access the +XPA Name Server (xpans). The default is +I<xpans_unix>. This variable is not usually needed. Note that +is the I<local> socket method is used, then remote machines will +not be able to access the xpans name server or the registered XPA access +points. + + + + +=item * + +B<XPA_NSUSERS> + + +This variable specifies whether other users' access points will be +returned by the +XPA Name Server (xpans) for use by +I<xpaget>, I<xpaset>, etc. +Generally speaking, it is sufficient to run one xpans name server per +machine and register the access points for all users with that xpans. +This means, for example, that if you request information from +ds9 by running: + + xpaget ds9 colormap + +you might get information from your own ds9 as well as +from another user running ds9 on the same machine. The +I<XPA_NSUSERS> variable controls whether you want such access +to the access points of other users. +By default, only your own access points are returned, so +that, in the example above, you would only get the colormap information +from the ds9 you registered. If, however, you had set the value of the +I<XPA_NSUSERS> variable to I<eric,fred>, then you would be +able to communicate with both eric and fred's access points. Note that +this variable can be overridden using the I<-u> switch on the +I<xpaget>, I<xpaset>, and I<xpainfo> programs. + + + + +=item * + +B<XPA_PORT> + + +A semi-colon delimited list of user specified ports to use for specific +XPA access points. The format is each specification is: + +class:template port1[ port2] + +where B<port1> is the main (command) port for the access point and +B<port2> is the (secondary) data port. If port2 is not specified, +it defaults to a value of 0 (meaning the system assigns the port). + + +Specification of specific ports is useful, for example, when a machine +outside a firewall needs to communicate with a machine inside a +firewall. In such a case, the firewall should be configured to allow +socket connections to both the command and data port from the outside +machine, and the inside XPA program should be started up with the +outside machine in its ACL list. Then, when the inside program is +started with specified ports, outside XPA programs can use +"machine:port" to contact the inside access points, instead of the +access point names. That is, the machine outside the firewall does not +need access to the XPA name server: + +export XPA_PORT="DS9:ds9 12345 12346" # on machine "inside" +cat foo.fits | xpaset inside:12345 fits # on machine "outside" + +Note that 2 ports are required for full XPA communication and +therefore 2 ports should be specified to go through a firewall. The +second port assignment is not important if you simply are assigning +the command port in order to communicate commands with a known +port (e.g., to bypass the xpans name server). If only one (command) +port is specified, the system will negotiate a random data port and +everything will work properly. + + +This support is somewhat experimental. If you run into problems, please +let us know. + + + + +=item * + +B<XPA_PORTFILE> + + +A list of user-specified port to use for specific xpa access points. +The format of the file is: + +class:template port1 [port2] + +where B<port1> is the main port for the access point and +B<port2> is the data port. If port2 is not specified, it defaults +to a value of 0 (meaning the system assigns the port). See +B<XPA_PORT> above for an explanation of user-specified ports. + + + + +=item * + +B<XPA_SHORT_TIMEOUT> + + +XPA is designed to allow data to be sent from one process to +another over a long period of time (i.e., a program that generates +image data sends that data to an image display, but slowly) but it +also seeks to prevent hangs. This is done by supporting 2 timeout +periods: a I<short> timeout for protocol communication +and a I<long> for data communication. + +The I<XPA_SHORT_TIMEOUT> variable +controls the I<short> timeout and is used to prevent hangs +in cases where the XPA protocol requires internal communication between +the client and server that is controlled by the XPA interface +itself. Authentication is an example of this sort of communication, +as is the establishment of a data channel between the two processes. +The default value for the I<short> is 30 seconds (which is +a pretty long time, actually). Setting the value to -1 will disable +I<short> timeouts and allow an infinite amount of time. + + + + +=item * + +B<XPA_SIGUSR1> + + +If the value of this variable is I<true>, then XPA will +catch SIGUSR1 signals when performing an I/O operation in order to +curtail that operation. This facility allows users to send a SIGUSR1 +signal to an XPA server if a client is hanging up the server by +sending or receiving data too slowly (timeouts also can be used -- see +above). When enabled in this way, the SIGUSR1 signal is ignored at all other +times, so that its safe to send the signal at any time. If the +variable is set to I<false>, then SIGUSR1 is not used at +all. Turning off SIGUSR1 would be desired in cases there the program +uses SIGUSR1 for some other reason and does not want XPA interfering. +The default is to use the signal. + + + + +=item * + +B<XPA_TIMESTAMP_ERRORS> + + +If I<XPA_TIMESTAMP_ERRORS> is I<true>, then error +messages will include a date/time string. This can be useful when +XPA errors are being saved in an error log (e.g. Web/CGI use). The +default is false. + + +=back + + + + + + +=item * + +B<XPA_TMPDIR> + + +This variable specifies the directory into which XPA logs, Unix +socket files (when I<XPA_METHOD> is I<local>), etc. are +stored. The default is I</tmp/.xpa>. + + + + +=item * + +B<XPA_VERBOSITY> + + +Specify the verbosity level of error messages. If the value is +set to I<0>, I<false>, or I<off>, then no error +messages are printed to stderr. If the value is I<1>, then +important XPA error messages will be output. If the value is +set to I<2>, XPA warnings about out-of-sync messages will also +be output. These latter almost always can be ignored. + + + + +=item * + +B<XPA_VERSIONCHECK> + + +Specify whether a new access point should check its major and minor XPA +version number against the version used by the xpans name server at +registration time. The default is I<true>. When checking is +performed, a warning is issued if the server major version is found to +be greater than the xpans version. Note that the check is performed +both by the XPA server and by the xpans process and warnings will be +issued by each. Also, instead of the values of I<true> or +I<false>, you can give this variable an integer value n. In this +case, each version checking process (i.e., the XPA-enabled server or +xpans) will print out a maximum of n warning messages (after which +version warnings are silently swallowed). + +In general, it is a bad idea to run an XPA-enabled server program +using a version of XPA newer than the basic xpaset, xpaget, xpaaccess, +xpans programs. This sort of mismatch usually will not work due to +protocol changes. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpafree.pod b/xpa/doc/pod/xpafree.pod new file mode 100644 index 0000000..4071fb2 --- /dev/null +++ b/xpa/doc/pod/xpafree.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + + + +B<XPAFree: remove an XPA public access point> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + int XPAFree(XPA xpa); + + + + + +=head1 DESCRIPTION + + + + +Remove the specified XPA public access point from the name server and +free all associated storage. Note that removal from the name server +happens automatically when the process terminates, so this call is not +generally needed. It is used when public access points are being +defined temporarily and then destroyed when no longer needed. For +example, ds9 temporarily creates a public access point when it +loads a new image for display and destroys it when the image is +unloaded. + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpaget.pod b/xpa/doc/pod/xpaget.pod new file mode 100644 index 0000000..77e771b --- /dev/null +++ b/xpa/doc/pod/xpaget.pod @@ -0,0 +1,67 @@ +=pod + +=head1 NAME + + + +B<xpaget: retrieve data from one or more XPA servers> + + + +=head1 SYNOPSIS + + + + + +xpaget [-h] [-i nsinet] [-m method] [-s] [-t sval,lval] [-u users] <template|host:port> [paramlist] + + + + + +=head1 OPTIONS + + + + + + -h print help message + -i access XPA point on different machine (override XPA_NSINET) + -m override XPA_METHOD environment variable + -n don't wait for the status message after server completes + -s enter server mode + -t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) + -u [users] XPA points can be from specified users (override XPA_NSUSERS) + --version display version and exit + + + + +=head1 DESCRIPTION + + + + +Data will be retrieved from access points matching the +template +or host:port. +A set of qualifying parameters can be appended. + +B<Examples:> + + csh> xpaget ds9 images + csh> xpaget myhost.harvard.edu:12345 + + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpagetfd.pod b/xpa/doc/pod/xpagetfd.pod new file mode 100644 index 0000000..5be9cfc --- /dev/null +++ b/xpa/doc/pod/xpagetfd.pod @@ -0,0 +1,133 @@ +=pod + +=head1 NAME + + + +B<XPAGetFd: retrieve data from one or more XPA servers and write to files> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + int XPAGetFd(XPA xpa, + char *template, char *paramlist, char *mode, + int *fds, char **names, char **messages, int n); + + + + + +=head1 DESCRIPTION + + + + +Retrieve data from one or more XPA servers whose class:name identifier +matches the specified +template +and write it to files associated with +one or more standard I/O fds (i.e, handles returned by open()). + + +A +template +of the form "class1:name1" is sent to the +XPA name server, which returns a list of at most ABS(n) matching XPA +servers. A connection is established with each of these servers and +the paramlist string is passed to the server as the data transfer +request is initiated. If an XPA struct is passed to the call, then the +persistent connections are updated as described above. Otherwise, +temporary connections are made to the servers (which will be closed +when the call completes). + + +The XPAGetFd() routine then retrieves data from the XPA servers, +and write these data to the fds associated with one or more fds +(i.e., results from open). Is n is positive, then there will be n fds +and the data from each server will be sent to a separate fd. If n is +negative, then there is only 1 fd and all data is sent to this single +fd. (The latter is how xpaget is implemented.) + + +A string containing the class:name and ip:port is stored in the name +array. If a given server returned an error or the server callback +sends a message back to the client, then the message will be stored in +the associated element of the messages array. NB: if specified, the +name and messages arrays must be of size n or greater. + + +The returned message string will be of the form: + + XPA$ERROR error-message (class:name ip:port) + +or + + XPA$MESSAGE message (class:name ip:port) + + +Note that when there is an error stored in an messages entry, the +corresponding bufs and lens entry may or may not be NULL and 0 +(respectively), depending on the particularities of the server. + + +The return value will contain the actual number of servers that were +processed. This value thus will hold the number of valid entries in +the bufs, lens, names, and messages arrays, and can be used to loop +through these arrays. In names and/or messages is NULL, no information is +passed back in that array. + + +The mode string is of the form: "key1=value1,key2=value2,..." +The following keywords are recognized: + + key value default explanation + ------ -------- -------- ----------- + ack true/false true if false, don't wait for ack from server (after callback completes) + + +The ack keyword is not very useful, since the server completes the callback +in order to return the data anyway. It is here for completion (and perhaps +for future usefulness). + + +B<Example:> + + #include <xpa.h> + #define NXPA 10 + int i, got; + int fds[NXPA]; + char *names[NXPA]; + char *messages[NXPA]; + for(i=0; i<NXPA; i++) + fds[i] = open(...); + got = XPAGetFd(NULL, "ds9", "file", NULL, fds, names, messages, NXPA); + for(i=0; i<got; i++){ + if( messages[i] != NULL ){ + /* error processing */ + fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]); + } + if( names[i] ) + free(names[i]); + if( messages[i] ) + free(messages[i]); + } + + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpainet.pod b/xpa/doc/pod/xpainet.pod new file mode 100644 index 0000000..40793a0 --- /dev/null +++ b/xpa/doc/pod/xpainet.pod @@ -0,0 +1,285 @@ +=pod + +=head1 NAME + + + +B<XPAInet: XPA Communication Between Hosts> + + + +=head1 SYNOPSIS + + + + +XPA uses standard inet sockets to support communication between two or +more host computers. + + + +=head1 DESCRIPTION + + + + + +When the Communication Method is set to +B<inet> (as it is by default), XPA can be used to communicate +between different computers on the Internet. INET sockets utilize the +IP address of the given machine and a (usually random) port number to +communicate between processes on the same machine or between different +machines on the Internet. These standard Internet sockets are also +used by programs such as Netscape, ftp. etc. + + +XPA supports a host-based Access Control mechanism +to prevent unauthorized access of XPA access points by other computers +on the Net. By default, only the machine on which the XPA server is +running can access XPA services. Therefore, setting up communication +between a local XPA server machine and a remote client machine +requires a two-part registration process: + + + +=over 4 + + + + +=item * + +the XPA service on the local machine must be made known to the +remote machine + + +=item * + +the remote machine must be given permission to access the local +XPA service + + +=back + + + +Three methods by which this remote registration can be accomplished +are described below. + +B<Manual Registration> + +The first method is the most basic and does not require the remote +client to have xpans running. To use it, the local server simply +gives a remote client machine access to one or more XPA access points +using xpaset and the B<-acl> sub-command. For example, +consider the XPA test program "stest" running on a local machine. By +default the access control for the access point named "xpa" is +restricted to that machine: + + [sh]$ xpaget xpa -acl + *:* 123.456.78.910 gisa + *:* localhost gisa + +Using xpaset and the B<-acl> sub-command, a remote client +machine can be given permission to perform xpaget, xpaset, xpaaccess, +or xpainfo operations. For example, to allow the xpaget operation, the +following command can be issued on the local machine: + + [sh]$ xpaset -p xpa -acl "remote_machine g" + +This results in the following access permissions on the local machine: + + [sh]$ xpaget xpa -acl + XPA:xpa 234.567.89.012 g + *:* 123.456.78.910 gisa + *:* localhost gisa + + +The remote client can now use the local server's xpans name server to +establish communication with the local XPA service. This can be done +on a call-by-call basis using the B<-i> switch on xpaset, xpaget, etc: + + [sh]$ xpaget -i "local_machine:12345" xpa + class: XPA + name: xpa + method: 88877766:2778 + sendian: little + cendian: big + +Alternatively, the XPA_NSINET variable on the remote machine can be +set to point directly to xpans on the local machine, removing +the need to override this value each time an XPA program is run: + + [csh]$ setenv XPA_NSINET 'karapet:$port' + [csh]$ xpaget xpa + class: XPA + name: xpa + method: 88877766:2778 + sendian: little + cendian: big + +Here, '$port' means to use the default XPA name service port (14285). +not a port environment variable. + + +Access permission for remote client machines can be stored in a file +on the local machine pointed to by the B<XPA_ACLFILE> environment +variable or using the B<XPA_DEFACL> environment variable. See <A +HREF="./acl.html">XPA Access Control for more information. + +B<Remote Registration> + +If xpans is running on the remote client machine, then a local xpaset +command can be used with the B<-remote> sub-command to +register the local XPA service in the remote name service, while at +the same time giving the remote machine permission to access the local +service. For example, assume again that "stest" is running on the +local machine and that xpans is also running on the remote machine. +To register access of this local xpa on the remote machine, use +the xpaset and the B<-remote> sub-command: + + [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' + + +To register the local xpa access point on the remote machine with xpaget +access only, execute: + + [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' g + +Once the remote registration command is executed, the remote client +machine will have an entry such as the following in its own xpans name +service: + + [csh]$ xpaget xpans + XPA xpa gs 88877766:2839 eric + +The xpa access point can now be utilized on the remote machine without +further setup: + + [csh]$ xpaget xpa + class: XPA + name: xpa + method: 838e2f68:2839 + sendian: little + cendian: big + +To unregister remote access from the local machine, use the same +command but with a '-' argument: + + [sh]$ xpaset -p xpa -remote 'remote_machine:$port' - + +The benefit of using remote registration is that communication with +remote access points can be mixed with that of other access points +on the remote machine. Using Access Point +Names and Templates, one XPA command can be used to send or +receive messages to the remote and local services. + +B<XPANS Proxy Registration> + +The two methods described above are useful when the local and remote +machines are able to communicate freely to one another. This would be +the case on most Local Area Networks (LANs) where all machines are +behind the same firewall and there is no port blocking between +machines on the same LAN. The situation is more complicated when the +XPA server is behind a firewall, where outgoing connections are +allowed, but incoming port blocking is implemented to prevent machines +outside the firewall from connecting to machines inside the +firewall. Such incoming port blocking will prevent xpaset and xpaget +from connecting to an XPA server inside a firewall. + + +To allow locally fire-walled XPA services to register with remote +machines, we have implemented a proxy service within the xpans name +server. To register remote proxy service, xpaset and the +B<-remote> sub-command is again used, but with an additional +B<-proxy> argument added to the end of the command: + + [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' g -proxy + +Once a remote proxy registration command is executed, the remote +machine will have an entry such as the following in its own xpans name +service: + + [csh]$ xpaget xpans + XPA xpa gs @88877766:2839 eric + +The '@' sign in the name service entry indicates that xpans proxy +processing is being used for this access point. Other than that, from +the user's point of view, there is no difference in how this XPA +access point is contacted using XPA programs (xpaset, xpaget, etc.) or +libraries: + + [csh]$ xpaget xpa + class: XPA + name: xpa + method: 88877766:3053 + sendian: little + cendian: big + + +Of course, the underlying processing of the XPA requests is very much +different when xpans proxy is involved. Instead of an XPA program such +contacting the XPA service directly, it contacts the local xpans. +Acting as a proxy server, xpans communicates with the XPA service +using the command channel established at registration time. Commands +(including establishing a new data channel) are sent between xpans and +the XPA service to set up a new message transfer, and then data is fed +to/from the xpa request, through xpans, from/to the XPA service. In +this way, it can be arranged so that connections between the +fire-walled XPA service and the remote client are always initiated by +the XPA service itself. Thus, incoming connections that would be +blocked by the firewall are avoided. Note that there is a performance +penalty for using the xpans/proxy service. Aside from extra overhead +to set up proxy communication, all data must be sent through the +intermediate proxy process. + + +The xpans proxy scheme requires that the remote client allow the local +XPA server machine to connect to the remote xpans/proxy server. If the +remote client machine also is behind a port-blocking firewall, such +connections will be disallowed. In this case, the only solution is to +open up some ports on the remote client machine to allow incoming +connections to xpans/proxy. Two ports must be opened (for command and +data channel connections). By default, these two ports are 14285 and +14287. The port numbers can be changed using the B<XPA_NSINET> +environment variable. This variable takes the form: + + setenv XPA_NSINET machine:port1[,port2[,port3]] + +where port1 is the main connecting port, port2 is the XPA access port, +and port3 is the secondary data connecting port. The second and third +ports are optional and default to port1+1 and port1+2, respectively. +It is port1 and port3 that must be left open for incoming connections. + + +For example, to change the port assignments so that xpans listens +for registration commands on port 12345 and data commands on port 28573: + + setenv XPA_NSINET myhost:12345 + +Alternatively, all three ports can be assigned explicitly: + + setenv XPA_NSINET remote:12345,3000,12346 + +In this case 12345 and 12346 should be open for incoming connections. +The XPA access port (which need not be open to the outside +world) is set to 3000. + + +Finally, note that we currently have no mechanism to cope with +Internet proxy servers (such as SOCKS servers). If an XPA service is +running on a machine that cannot connect directly to outside machines, +but goes through a proxy server instead, there currently is no way to +register that XPA service with a remote machine. We hope to implement +support for SOCKS proxy in a future release. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpainfo.pod b/xpa/doc/pod/xpainfo.pod new file mode 100644 index 0000000..65fdb3e --- /dev/null +++ b/xpa/doc/pod/xpainfo.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + + + +B<xpainfo: send short message to one or more XPA servers> + + + +=head1 SYNOPSIS + + + + + +xpainfo [-h] [-i nsinet] [-m method] [-n] [-s] [-t sval,lval] [-u users] <template|host:port> [paramlist] + + + + + +=head1 OPTIONS + + + + + + -h print help message + -i access XPA point on different machine (override XPA_NSINET) + -m override XPA_METHOD environment variable + -n don't wait for the status message after server completes + -s enter server mode + -t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) + -u [users] XPA points can be from specified users (override XPA_NSUSERS) + --version display version and exit + + + + +=head1 DESCRIPTION + + + + +Info will be sent to access points matching the +template +or host:port. +A set of qualifying parameters can be appended. + +B<Examples:> + + csh> xpainfo IMAGE ds9 image + + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpainfonew.pod b/xpa/doc/pod/xpainfonew.pod new file mode 100644 index 0000000..ae54f54 --- /dev/null +++ b/xpa/doc/pod/xpainfonew.pod @@ -0,0 +1,92 @@ +=pod + +=head1 NAME + + + +B<XPAInfoNew: define an XPA info public access point> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + XPA XPAInfoNew(char *class, char *name, + int (*info_callback)(), + void *info_data, char *info_mode); + + + + + +=head1 DESCRIPTION + + + + +[NB: this is an experimental interface, new to XPA 2.0, whose value +and best use is evolving.] + + +A program can register interest in receiving a short message about a +particular topic from any other process that cares to send such a +message. Neither has to be an XPA server. For example, if a user +starts to work with a new image file called new.fits, she might +wish to alert interested programs about this new file by sending a +short message using xpainfo: + + xpainfo IMAGEFILE /data/new.fits + + + +In this example, each process that has used the XPAInfoNew() call to +register interest in messages associated with the identifier IMAGEFILE +will have its info_callback() executed with the following calling +sequence: + + int info_cb(void *info_data, void *call_data, char *paramlist) + { + XPA xpa = (XPA)call_data; + } + + +The arguments passed to this routine are equivalent to those sent in +the send_callback() routine. The main difference is that there is no +buf sent to the info callback: this mechanism is meant for short +announcement of messages of interest to many clients. + + +The mode string is of the form: "key1=value1,key2=value2,..." +The following keywords are recognized: + + key value default explanation + ------ -------- -------- ----------- + acl true/false true enable access control + + +Because no buf is passed to this callback, the usual buf-related keywords +are not applicable here. + + +The information sent in the parameter list is arbitrary. However, we +envision sending information such as file names or XPA access points +from which to collect more data. Note that the xpainfo program and +the XPAInfo() routine that cause the info_callback to execute do not +wait for the callback to complete before returning. + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpaintro.pod b/xpa/doc/pod/xpaintro.pod new file mode 100644 index 0000000..31ce14f --- /dev/null +++ b/xpa/doc/pod/xpaintro.pod @@ -0,0 +1,176 @@ +=pod + +=head1 NAME + + + +B<XPAIntro: Introduction to the XPA Messaging System> + + + +=head1 SYNOPSIS + + + + + +A brief introduction to the XPA messaging system, which provides +seamless communication between all kinds of Unix event-driven +programs, including X programs, Tcl/Tk programs, and Perl programs. + + + +=head1 DESCRIPTION + + + + + +The XPA messaging system provides seamless communication between all +kinds of Unix programs, including X programs, Tcl/Tk programs, and +Perl programs. It also provides an easy way for users to communicate +with these XPA-enabled programs by executing XPA client commands in +the shell or by utilizing such commands in scripts. Because XPA works +both at the programming level and the shell level, it is a powerful +tool for unifying any analysis environment: users and programmers have +great flexibility in choosing the best level or levels at which to +access XPA services, and client access can be extended or modified +easily at any time. + + +A program becomes an XPA-enabled server by defining named points of +public access through which data and commands can be exchanged with +other client programs (and users). Using standard TCP sockets as +a transport mechanism, XPA supports both single-point and broadcast +messaging to and from these servers. It supports direct communication +between clients and servers, or indirect communication via an +intermediate message bus emulation program. Host-based access control +is implemented, as is as the ability to communicate with XPA servers +across a network. + + +XPA implements a layered interface that is designed to be useful both +to software developers and to users. The interface consists of a +library of XPA client and server routines for use in programs and a +suite of high-level user programs built on top of these libraries. +Using the XPA library, access points can be added to +Tcl/Tk +programs, +Xt +programs, or to Unix programs that use the XPA event loop or any +event loop based on select(). Client access subroutines can be added +to any Tcl/Tk or Unix program. Client access also is supported at the +command line via a suite of high-level programs. + + +The major components of the XPA layered interface are: + + +=over 4 + + + + +=item * + +A set of XPA server routines, centered on +XPANew(), +which are used by XPA server programs to tag public access points with +string identifiers and to register send and receive callbacks for +these access points. + + + +=item * + +A set of XPA client routines, centered on the +XPASet() +and +XPAGet(), +which are used by external client applications to exchange data and +commands with an XPA server. + + + +=item * + +High-level programs, centered on +xpaset +and +xpaget, +which allow data +and information to be exchanged with XPA server programs from the +command line and from scripts. These programs have the command syntax: + + [data] | xpaset [qualifiers ...] + xpaget [qualifiers ...] + + + +=item * + +An XPA name server program, +xpans, +through which XPA access point names are +registered by servers and distributed to clients. + + +=back + + + + +Defining an XPA access point is easy: a server application calls +XPANew(), +XPACmdNew(), +or the experimental +XPAInfoNew() +routine to +create a named public access point. An XPA service can specify "send" +and "receive" callback procedures (or an "info" procedure in the case +of XPAInfoNew()) to be executed by the program when an external +process either sends data or commands to this access point or requests +data or information from this access point. Either of the callbacks +can be omitted, so that a particular access point can be specified as +read-only, read-write, or write-only. Application-specific client +data can be associated with these callbacks. Having defined one or +more public access points in this way, an XPA server program enters +its usual event loop (or uses the standard XPA event loop). + + +Clients communicate with these XPA public access points +using programs such as +xpaget, +xpaset, and +xpainfo +(at the command line), +or routines such as +XPAGet(), +XPASet(), +and +XPAInfo() +within a program. Both methods require specification of the name of +the access point. The xpaget program returns data or other +information from an XPA server to its standard output, while the +xpaset program sends data or commands from its standard input to an +XPA application. The corresponding API routines set/get data to/from +memory, returning error messages and other info as needed. If a +template +is used to specify the access point name (e.g., "ds9*"), then +communication will take place with all servers matching that template. + + +Please note that XPA currently is not thread-safe. All XPA calls must be +in the same thread. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpamacros.pod b/xpa/doc/pod/xpamacros.pod new file mode 100644 index 0000000..786e04b --- /dev/null +++ b/xpa/doc/pod/xpamacros.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + + + +B<XPA Server Callback Macros> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + xpa_class, xpa_name, xpa_method, xpa_cmdfd, xpa_datafd, + xpa_sendian, xpa_cendian + + + + + +=head1 DESCRIPTION + + + + +Server routines have access to information about the XPA being called via +the following macros (each of which takes the xpa handle as an argument): + + macro explanation + ------ ----------- + xpa_class class of this xpa + xpa_name name of this xpa + xpa_method method string (inet or local connect info) + xpa_cmdfd fd of command socket + xpa_datafd fd of data socket + xpa_sendian endian-ness of server ("little" or "big") + xpa_cendian endian-ness of client ("little" or "big" + + +The argument to these macros is the call_data pointer that is passed +to the server procedure. This pointer should be type case to XPA +in the server routine: + + XPA xpa = (XPA)call_data; + + + +The most important of these macros is xpa_datafd(). A server routine +that sets "fillbuf=false" in receive_mode or send_mode can use this +macro to perform I/O directly to/from the client, rather than using +buf. + + +The xpa_cendian and xpa_sendian macros can be used together to determine +if the data transferred from the client is byte swapped with respect +to the server. Values for these macros are: "little", "big", or "?". +In order to do a proper conversion, you still need to know the format +of the data (i.e., byte swapping is dependent on the size of the data +element being converted). + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpamainloop.pod b/xpa/doc/pod/xpamainloop.pod new file mode 100644 index 0000000..4fabf8e --- /dev/null +++ b/xpa/doc/pod/xpamainloop.pod @@ -0,0 +1,108 @@ +=pod + +=head1 NAME + + + +B<XPAMainLoop: optional main loop for XPA> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + void XPAMainLoop(); + + + + + +=head1 DESCRIPTION + + + + +Once XPA access points have been defined, a program must enter an +event loop to watch for requests from external programs. This can be +done in a variety of ways, depending on whether the event loop is +processing events other than XPA events. In cases where there are no +non-XPA events to be processed, the program can simply call the +XPAMainLoop() event loop. This loop is implemented essentially as +follows (error checking is simplified in this example): + + FD_ZERO(&readfds); + while( XPAAddSelect(NULL, &readfds) ){ + if( sgot = select(swidth, &readfds, NULL, NULL, NULL) >0 ) + XPAProcessSelect(&readfds, 0); + else + break; + FD_ZERO(&readfds); + } + + +The XPAAddSelect() routine sets up the select() readfds variable so +that select() will wait for I/O on all the active XPA channels. It +returns the number of XPAs that are active; the loop will end when +there are no active XPAs. The standard select() routine is called to +wait for an external I/O request. Since no timeout struct is passed +in argument 5, the select() call hangs until there is an external +request. When an external I/O request is made, the XPAProcessSelect() +routine is executed to process the pending requests. In this routine, +the maxreq value determines how many requests will be processed: if +maxreq <=0, then all currently pending requests will be processed. +Otherwise, up to maxreq requests will be processed. (The most usual +values for maxreq is 0 to process all requests.) + + +If a program has its own Unix select() loop, then XPA access points can +be added to it by using a variation of the standard XPAMainLoop: + + XPAAddSelect(xpa, &readfds); + [app-specific ...] + if( select(width, &readfds, ...) ){ + XPAProcessSelect(&readfds, maxreq); + [app-specific ...] + FD_ZERO(&readfds); + } + + +XPAAddSelect() is called before select() to add the access points. +If the first argument is NULL, then all active XPA access points +are added. Otherwise only the specified access point is added. +After select() is called, the XPAProcessSelect() routine can be called +to process XPA requests. Once again, the maxreq value determines how +many requests will be processed: if maxreq <=0, then all currently +pending requests will be processed. Otherwise, up to maxreq requests +will be processed. + + +XPA access points can be added to +Xt event loops (using XtAppMainLoop()) +and +Tcl/Tk event loops (using vwait and the Tk loop). +When using XPA with these event loops, you only need to call: + +int XPAXtAddInput(XtAppContext app, XPA xpa) + +or + + int XPATclAddInput(XPA xpa) + +respectively before entering the loop. + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpamb.pod b/xpa/doc/pod/xpamb.pod new file mode 100644 index 0000000..fb8ef7c --- /dev/null +++ b/xpa/doc/pod/xpamb.pod @@ -0,0 +1,249 @@ +=pod + +=head1 NAME + + + +B<xpamb: the XPA Message Bus> + + + +=head1 SYNOPSIS + + + + + +The xpamb program can act as a "classical" message bus interface +between clients and servers. A client can send a data request to +the message bus, which then interfaces with multiple servers and +returns the data back to the client. + + + +=head1 OPTIONS + + + + + +For xpaset, several optional switches are used to save data and +manipulate the stored data: + + +=over 4 + + + + + + +=item * + +B<-data [name]> + + +Add the supplied data buffer to a pool of stored data buffers, +using the specified name as a unique identifier for later retrieval. +An error occurs if the name already exists (use either B<replace> +or B<del> to rectify this). The B<-add> switch is supported +for backwards compatibility with xpa 2.0. + + + + +=item * + +B<-replace [name]> + + +Replace previously existing stored data having the same unique name +with new data. This essentially is a combination of the B<del> +and B<data> commands. + + + + +=item * + +B<-info ["'info string'"]> + + +When adding a data buffer, you can specify an informational +string to be stored with that data. This string will be returned +by xpaget: + + xpaget xpamb foo -info + +(along with other information such as the date/time of storage and the size of +the data buffer) if the -info switch is specified. If the info string contains +spaces, you must enclose it in B<two> sets of quotes: + + cat foo | xpaset xpamb -data foo -info "'this is info on foo'" + +The first set of quotes is removed by the shell while the second is used to +delineate the info string. + + + + +=item * + +B<-send [name]> + + +Broadcast the stored data buffer to the named template. + + + + +=item * + +B<-del [name]> + + +Delete the named data buffer and free all allocated space. + + +=back + + + + +Switches can be used in any combination that makes sense. For example: + + cat foo.fits | xpaset xpamb -data foo -info "FITS" "DS9:*" fits foo.fits + +will broadcast the foo.fits image to all access points of class +B<DS9>. In addition, the foo.fits file will be stored under the +name of B<foo> for later manipulation such as: + + xpaset -p xpamb -send foo "DS9:*" fits foo.fits + +will re-broadcast the foo.fits image to all access points of class "DS9". + + + +=head1 DESCRIPTION + + + + + +A "classical" message bus (such as ToolTalk) consists of servers and +clients, along with a mediating program that transfers data between +different processes. XPA takes a slightly different approach in that +communication between clients and servers is direct. This generally +is the correct technique when there is only one connection (or even a +small number of connections), but can become inefficient for the +serving program if a large amount of data is being transferred to many +clients. For example, if a real-time data acquisition program is +broadcasting a FITS image to several clients, it would need to +transmit that image to each client individually. This might interfere +with its own processing cycles. The preferable mechanism would be to +pass the image off to an intermediate program that can then broadcast +the data to the several clients. + +The B<xpamb> program can alleviate such problems by functioning +as a message bus in cases where such an intermediary process is +wanted. It pre-defines a single access point named +B<XPAMB:xpamb> to which data can be sent for re-broadcast. You +also can tell B<xpamb> to save the data, and associate with that +data a new access point, so that it can be retrieved later on. + + +All interaction with B<xpamb> is performed through +B<xpaset> and B<xpaget> (or the corresponding API +routines, B<XPASet()> and B<XPAGet()>) to the +B<XPAMB:xpamb> access point. That is, B<xpamb> is just +another XPA-enabled program that responds to requests from +clients. The paramlist is used to specify the targets to which +the data will be for re-broadcast, as well as the re-broadcast paramlist: + + data | xpaset xpamb [switches] broadcast-target broadcast-paramlist + +Optional switches are used to store data, and manipulate stored data, +and are described below. + + +In its simplest form, you can, for example, send a FITS image to xpamb for +broadcasting to all ds9 image simply by executing: + + cat foo.fits | xpaset xpamb "DS9:*" fits foo.fits + +Since B<DS9> is the class name for the ds9 image display +program, this will result in the FITS image being re-sent to all fits +access points for all active image display programs. + + +You can send stored data and new data to the same set of access points at +the same time. The stored data always is sent first, followed by the new +data: + + cat foo2.fits | xpaset xpamb -send foo "DS9:*" fits foo.fits + +will first send the foo.fits file, and then the foo2.fits file to all +access points of class B<DS9>. Notice that in this example, +the foo2.fits file is not stored, but it could be stored by using the +B<-store [name]> switch on the command line. + + +The B<xpaget> command can be used to retrieve a data from XPA +access points or from a stored data buffer, or retrieve information +about a stored data buffer. If no arguments are given: + + xpaget xpamb + +then information about all currently stored data buffers is returned. This +information includes the data and time at which the data was stored, the +size in bytes of the data, and the supplied info string. + + +If arguments are specified, they will be in the form: + + xpaget xpamb [-info] [-data] [name [paramlist]] + +If the optional B<-info> and/or B<-data> switches are specified, then +information and/or data will be returned for the named data buffer +following the switches. You can use either or both of these switches +in a single command. For example, if the -info switch is used: + + xpaget xpamb -info foo + +then the info about that stored data buffer will be returned. +If the -data is used with a specific name: + + xpaget xpamb -data foo + +then the stored data itself will be returned. If both are used: + + xpaget xpamb -info -data foo + +then the info will be returned, followed by the data. Note that it is an +error to specify one of these switches without a data buffer name and that +the paramlist will be ignored. + + +If neither the B<-info> or B<-data> switch is specified, then +the name refers to an XPA access point (with an optional paramlist +following). +For example: + + xpaget xpamb ds9 file + +is equivalent to: + + xpaget ds9 file + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpamethod.pod b/xpa/doc/pod/xpamethod.pod new file mode 100644 index 0000000..038ac4e --- /dev/null +++ b/xpa/doc/pod/xpamethod.pod @@ -0,0 +1,99 @@ +=pod + +=head1 NAME + + + +B<XPAMethod: XPA Communication Methods> + + + +=head1 SYNOPSIS + + + + + +XPA supports both inet and unix (local) socket communication. + + + +=head1 DESCRIPTION + + + + + +XPA uses sockets for communication between processes. It supports +three methods of socket communication: inet, localhost, and unix. In +general, the same method should be employed for all XPA processes in a +session and the global environment variable XPA_METHOD should be used +to set up the desired method. By default, the preferred method is +"inet", which is appropriate for most users. You can set up a +different method by typing something like: + + setenv XPA_METHOD local # unix csh + XPA_METHOD=local; export XPA_METHOD # unix sh, bash, windows/cygwin + set XPA_METHOD=localhost # dos/windows + +The options for XPA_METHOD are: B<inet>, B<unix> (or +B<local>), and B<localhost>. On Unix machines, this +environment setup command can be placed in your shell init file +(.cshrc, .profile, .bashrc, etc.) On Windows platforms, it can be +placed in your AUTOEXEC.BAT file (I think!). + + +By default, B<inet> sockets are used by XPA. These are the standard +Internet sockets that are used by programs such as Netscape, +ftp. etc. Inet sockets utilize the IP address of the given machine and +a (usually random) port number to communicate between processes on the +same machine or between different machines on the Internet. (Note that +XPA has an Access Control mechanism to +prevent unauthorized access of XPA access points by other computers on +the Net). For users connected to the Internet, this usually is the +appropriate communication method. For more information about setting +up XPA communication between machines, see +Communication Between Machines. + + +In you are using XPA on a machine without an Internet connection, then +inet sockets are not appropriate. In fact, an XPA process often will +hang for many seconds while waiting for a response from the Domain +Name Service (DNS) when using inet sockets. Instead of inet sockets, +users on Unix platforms can also use B<unix> sockets (also known +as local sockets). These sockets are based on the local file system +and do not make use of the DNS. They generally are considered to be +faster than inet sockets, but they are not implemented under +Windows. Use local sockets as a first resort if you are on a Unix +machine that is not connected to the Internet. + + +Users not connected to the Internet also can use B<localhost> +sockets. These are also inet-type sockets but the IP address used for +the local machine is the B<localhost> address, 0x7F000001, instead +of the real IP of the machine. Depending on how sockets are set up for +a given platform, communication with the DNS usually is not required in +this case (though of course, XPA cannot interact with other machines). +The localhost method will generally work on both Unix and Windows +platforms, but whether the DNS is required or not is subject to +individual configurations. + + +A final warning/reminder: if your XPA-enabled server hangs at startup +time and your XPA_METHOD is B<inet>, the problem probably is +related to an incorrect Internet configuration. This can be confirmed +by using the B<unix> method or (usually) the B<localhost> +method. You can use these alternate methods if other hosts do not need +access to the XPA server. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpaname.pod b/xpa/doc/pod/xpaname.pod new file mode 100644 index 0000000..7c0ea8d --- /dev/null +++ b/xpa/doc/pod/xpaname.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + + + +B<XPAName: What does XPA stand for?> + + + +=head1 SYNOPSIS + + + + + +What does XPA stand for? Who knows anymore! + + + +=head1 DESCRIPTION + + + + + +What does XPA stand for? Dunno! The XPA messaging system originally +was built on top of the X Window System and XPA was the mnemonic for +I<X Public Access>, to emphasize that we were providing public +access to previously private data and algorithms in Xt programs. Now +that XPA no longer is tied to X, it can be argued that we ought to +change the name (how about SPAM: simple public access mechanism +), but XPA is in wide-spread use in the astronomical community of +its birth, and the name has taken on a life of its own. If anyone can +think of what XPA now means, please let us know. + + +If you think this is bad, consider the MMT Telescope on Mount Hopkins, +Arizona. When first installed twenty years ago, it featured an array +of six 72-inch diameter mirrors. from which came its name: the +I<Multiple Mirror Telescope>. In spring of 1999, these mirrors +were replaced by a single 21 and 1/2 -foot diameter primary mirror, +the largest single-piece glass reflector on the North American +continent. And now MMT stands for ... MMT! + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpanew.pod b/xpa/doc/pod/xpanew.pod new file mode 100644 index 0000000..1a3800f --- /dev/null +++ b/xpa/doc/pod/xpanew.pod @@ -0,0 +1,243 @@ +=pod + +=head1 NAME + + + +B<XPANew: create a new XPA access point> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + XPA XPANew(char *class, char *name, char *help, + int (*send_callback)(), + void *send_data, char *send_mode, + int (*rec_callback)(), + void *rec_data, char *rec_mode); + + + + + +=head1 DESCRIPTION + + + + +Create a new XPA public access point with the class:name +identifier template +and enter this access point into the XPA name server, so that it +can be accessed by external processes. XPANew() returns an XPA struct. +Note that the length of the class and name designations must be less +than or equal to 1024 characters each. + + +The XPA name server daemon, xpans, will be started automatically if it +is not running already (assuming it can be found in the path). The +program's ip address and listening port are specified by the +environment variable XPA_NSINET, which takes the form :. If +no such environment variable exists, then xpans is started on the +current machine listening on port 14285. It also uses 14286 as a +known port for its public access point (so that routines do not have +to go to the name server to find the name server ip and port!) +As of XPA 2.1.1, version information is exchanged between the xpans +process and the new access point. If the access point uses an XPA +major/minor version newer than xpans, a warning is issued by both processes, +since mixing of new servers and old xpa programs (xpaset, xpaget, +xpans, etc.) is not likely to work. You can turn off the warning +message by setting the XPA_VERSIONCHECK environment variable to "false". + + +The help string is meant to be returned by a request from xpaget: + + xpaget class:name -help + + +A send_callback and/or a receive_callback can be specified; at +least one of them must be specified. + + +A send_callback can be specified that will be executed in response to +an external request from the xpaget program, the XPAGet() routine, or +XPAGetFd() routine. This callback is used to send data to the +requesting client. + + +The calling sequence for send_callback() is: + + int send_callback(void *send_data, void *call_data, + char *paramlist, char **buf, size_t *len) + { + XPA xpa = (XPA)call_data; + ... + return(stat); + } + + +The send_mode string is of the form: "key1=value1,key2=value2,..." +The following keywords are recognized: + + key value default explanation + ------ -------- -------- ----------- + acl true/false true enable access control + freebuf true/false true free buf after callback completes + + +The call_data should be recast to the XPA struct as shown. In +addition, client-specific data can be passed to the callback in +send_data. + + +The paramlist will be supplied by the client as qualifying parameters +for the callback. There are two ways in which the send_callback() +routine can send data back to the client: + + +1. The send_callback() routine can fill in a buffer and pass back a +pointer to this buffer. An integer len also is returned to specify the +number of bytes of data in buf. XPA will send this buffer to the +client after the callback is complete. + + +2. The send_callback can send data directly to the client by writing +to the fd pointed by the macro: + + xpa_datafd(xpa) + + +Note that this fd is of the kind returned by socket() or open(). + + +If a buf has been allocated by a standard malloc routine, filled, and +returned to XPA, then freebuf generally is set so that the buffer will +be freed automatically when the callback is completed and data has +been sent to the client. If a static buf is returned, freebuf should +be set to false to avoid a system error when freeing static storage. +Note that default value for freebuf implies that the callback will +allocate a buffer rather than use static storage. + + +On the other hand, if buf is dynamically allocated using a method +other than a standard malloc/calloc/realloc routine (e.g. using Perl's +memory allocation and garbage collection scheme), then it is necessary +to tell XPA how to free the allocated buffer. To do this, use the +XPASetFree() routine within your callback: + + void XPASetFree(XPA xpa, void (*myfree)(void *), void *myfree_ptr); + +The first argument is the usual XPA handle. The second argument is the +special routine to call to free your allocated memory. The third +argument is an optional pointer. If not NULL, the specified free +routine is called with that pointer as its sole argument. If NULL, the +free routine is called with the standard buf pointer as its sole +argument. This is useful in cases where there is a mapping between the +buffer pointer and the actual allocated memory location, and the +special routine is expecting to be passed the former. + + +If, while the callback performs its processing, an error occurs that +should be communicated to the client, then the routine XPAError should be +called: + + XPAError(XPA xpa, char *s); + + +where s is an arbitrary error message. The returned error message +string will be of the form: + + XPA$ERROR [error] (class:name ip:port) + + +If the callback wants to send a specific acknowledgment message back +to the client, the routine XPAMessage can be called: + + XPAMessage(XPA xpa, char *s); + + +where s is an arbitrary error message. The returned error message +string will be of the form: + + XPA$MESSAGE [message] (class:name ip:port) + + +Otherwise, a standard acknowledgment is sent back to the client +after the callback is completed. + + +The callback routine should return 0 if no error occurs, or -1 to +signal an error. + + +A receive_callback can be specified that will be executed in response +to an external request from the xpaset program, or the XPASet (or +XPASetFd()) routine. This callback is used to process data received +from an external process. + + +The calling sequence for receive_callback is: + + int receive_callback(void *receive_data, void *call_data, + char *paramlist, char *buf, size_t len) + { + XPA xpa = (XPA)call_data; + ... + return(stat); + } + + +The mode string is of the form: "key1=value1,key2=value2,..." +The following keywords are recognized: + + key value default explanation + ------ -------- -------- ----------- + acl true/false true enable access control + buf true/false true server expects data bytes from client + fillbuf true/false true read data into buf before executing callback + freebuf true/false true free buf after callback completes + + +The call_data should be recast to the XPA struct as shown. In +addition, client-specific data can be passed to the callback in +receive_data. + + +The paramlist will be supplied by the client. In addition, if the +receive_mode keywords buf and fillbuf are true, then on entry into the +receive_callback() routine, buf will contain the data sent by the +client. If buf is true but fillbuf is false, it becomes the callback's +responsibility to retrieve the data from the client, using the data fd +pointed to by the macro xpa_datafd(xpa). If freebuf is true, then buf +will be freed when the callback is complete. + + +If, while the callback is performing its processing, an error occurs +that should be communicated to the client, then the routine XPAError +can be called: + + XPAError(XPA xpa, char *s); + + +where s is an arbitrary error message. + + +The callback routine should return 0 if no error occurs, or -1 to +signal an error. + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpans.pod b/xpa/doc/pod/xpans.pod new file mode 100644 index 0000000..071dd68 --- /dev/null +++ b/xpa/doc/pod/xpans.pod @@ -0,0 +1,226 @@ +=pod + +=head1 NAME + + + +B<xpans: the XPA Name Server> + + + +=head1 SYNOPSIS + + + + + + xpans [-h] [-e] [-k sec] [-p port] [-l log] [-s security log] [-P n] + + + + +=head1 OPTIONS + + + + + + -h print help message + -e exit when there are no more XPA connections + -k send keepalive messages every n sec + -l log data base entries to specified file + -p listen for connections on specified port + -s log security info for each connection to specified file + -P accept proxy requests (P=1) using separate thread (P=2) + --version display version and exit + + + + +=head1 DESCRIPTION + + + + +The xpans name server is an XPA-enabled program that is used to +manage the names and ports of XPA access points. It is started +automatically when an XPA access point is registered. You can access +the name server using xpaget to get a list of registered access points. + +The I<xpans> name server provides a crucial link between XPA +clients and servers. When an XPA server defines an access point using +XPANew(), XPACmdNew(), or XPAInfoNew(), the name of the access point +is registered in the name service, along with connection information. +The name server then matches class:name templates passed to it by XPA +clients with these registered entries, so that the clients can +communicate with the appropriate servers. + + +The socket connection between an XPA-enabled program and +I<xpans> is kept open until the former exits (or explicitly +closes the connection). Apparently, some Internet equipment (e.g. DSL +modems) can cause such a connection to time-out after a period of +inactivity. To prevent this from happening, you can use the -k +[sec] switch to send a short keep-alive message to each open +connection after the specified time delay. (Note that this +application level use of keep-alive is necessary only if you are +serving XPA-enabled clients over the Internet and have to deal with +long-term connections involving DSL or similar equipment. XPA uses +the ordinary socket-level keep-alive, which works for all other cases.) +NB (12/2/2009): Out-of-band (URG) TCP data, used by xpans +keep-alive, is changed by some Cisco routers into in-band data. +Encountering such a router will break the keep-alive function and may +break your XPA server as well. Proceed with caution! + + +The I<xpans> program will be started automatically (assuming it +can be found in the user's path) when the first XPA access point is +registered. It therefore need not be started explicitly. However, +when started automatically, the I<-e> switch is used, so that +the name server will exit when there are no more XPA access points +registered. If you wish to keep the name server running continually, +simply start it manually without the I<-e> switch. + + +The name server will keep a log of registered access points if the +I<-l [log]> switch is used on the command line (this is the +case for automatic start-up). The log contains enough name and connection +information to allow you to re-register all XPA access points in case +the name server process is terminated prematurely. For example, after +the ds9 access point is registered,the log will contain the entry: + + add 838e2f67:1863 ds9 ds9 gs eric + +If I<xpans> is terminated but ds9 still is running, you +can re-register both access points for the ds9 process by running: + + xpaset -p 838e2f67:1863 -nsconnect + +Notice that the ip:port specifier is used with I<xpaset> to bypass +the need for contacting the name server (which does not have the name +registered yet!) + + +The name server will keep a log of security information if the -s +[security log] switch is used on the command line. For each +accepted connection, (including connections via the I<xpaget> +command), information will be logged about the host issuing the +command and the parameters passed into the program. This is most +useful when I<xpans> is accepting connections from untrusted +machines. + + +When an XPA access point is removed by a server using I<XPAFree()>, +the access information is removed from the name server. If an +XPA-enabled process is terminated, all names registered by that process +will be removed automatically. The log file is always updated to +reflect the currently registered access points. + + +The name server itself has an XPA access point names I<xpans> +registered through which you can find out information about currently +registered access points (assuming you have access to the name server; +see XPA Access Control for more information). +For each registered access point, the following information is returned: + + class # class of the access point + name # name of the access point + access # allowed access (g=xpaget,s=xpaset,i=xpainfo) + id # socket access method (host:port for inet, file for local/unix) + user # user name of access point owner + + + +For example, to display all currently registered access points, simply execute: + + xpaget xpans + +Continuing the example of ds9 above, this will return: + + DS9 ds9 gs 838e2f67:1863 eric + +If the same program has been started with different XPA access names, +you can look up only names matching a specified template. For example, +assume that ds9 has been started up using: + + ds9 & + ds9 -title ds9-1-eric & + ds9 -title ds9-2-eric & + +To lookup all ds9 access points which end in ".eric" and which can +be accessed using I<xpaset>, use: + + xpaget xpans "DS9:*.eric" "s" "*" + +This will return: + + DS9 ds9-2-eric gs 838e29d3:42102 eric + DS9 ds9-1-eric gs 838e29d3:42105 eric + +The third argument "*" requests all access points from all users. +You also can specify a specific user name and only access points +registered by that user will be returned. + + +The name server uses the I<XPA_METHOD> environment variable +to determine whether it should listen for requests on INET or LOCAL +sockets. Since XPA access points also use this environment variable, +the choice of socket method will be consistent. Note that, when INET +sockets are used, a local server can be accessed from remote machines +if the I<XPA_NSINET> environment variable is set to point to +the local machine. See +XPA Environment Variables +for more information. + + +An experimental feature of xpans is its ability to act as a proxy to +XPA servers behind firewalls that want to communicate with external +processes. The basic idea is the following: an XPA server (call it +"foo") on host1, possibly behind a firewall, makes a remote connection +to a proxy-enabled xpans program on host2 (specifying host2's XPA method). +For example: + + xpaset -p foo -remote 'host2:28571' + -proxy # on host1 + +When this is done, host2 can use xpaset, xpaget, and xpainfo calls to +communicate with the XPA server foo. All command communication is +performed via the xpans socket connection between foo on host1 and +xpans on host2 (which was initiated by foo from inside the firewall). +Data communication is similarly performed using a socket connection +initiated on host1 (usually with a port value two greater than the +port value of the main xpans socket connection). An xpaset or xpaget +call on host2 contacts xpans, which performs an XPASet() or XPAGet() +call to foo, passing commands and data back and forth between the two +programs. + + +By default, proxy connections are not allowed by xpans. If the -P switch is +specified with a value of 1, proxy connection are allowed, but all proxy +communication is performed in the same thread as xpans processing. If +a value of 2 is specified, the proxy processing is performed in a +separate thread (assuming pthreads are supported on your system). +Because xpa callback processing of any type can take a long time and +therefore can interfere with normal xpans processing, threaded proxy +connections (-P 2) are recommended. When using proxy connections, it +might also be useful to set the XPA_IOCALLSXPA environment variable, so +that multiple proxy requests can be handled at the same time, instead of +serially. + + +Note that this proxy interface to xpans is experimental. It is used +to provide remote data analysis capabilities on the Chandra-Ed system +using ds9. (See http://chandra-ed.cfa.harvard.edu and +http://hea-www.harvard.edu/saord/ds9 for more details). As always, please +contact us if you have problems or questions. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpanslookup.pod b/xpa/doc/pod/xpanslookup.pod new file mode 100644 index 0000000..e0f4cdc --- /dev/null +++ b/xpa/doc/pod/xpanslookup.pod @@ -0,0 +1,126 @@ +=pod + +=head1 NAME + + + +B<XPANSLookup: lookup registered XPA access points> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + int XPANSLookup(XPA xpa, + char *template, char type, + char ***classes, char ***names, + char ***methods, char ***infos) + + + + + +=head1 DESCRIPTION + + + + +XPA routines act on a class:name identifier in such a way +that all access points that match the identifier are processed. It is +sometimes desirable to choose specific access points from the +candidates that match the +template. In order to do this, the +XPANSLookup routine can be called to return a list of matches, so that +specific class:name instances can then be fed to XPAGet(), XPASet(), etc. + + The first argument is an optional XPA struct. If non-NULL, the +existing name server connection associated with the specified xpa is +used to query the xpans name server for matching templates. Otherwise, +a new (temporary) connection is established with the name server. + + +The second argument to XPANSLookup is the class:name +template +to match. + + +The third argument for XPANSLookup() is the type of access and can be +any combination of: + + type explanation + ------ ----------- + g xpaget calls can be made on this access point + s xpaset calls can be made on this access point + i xpainfo calls can be made on this access point + + +The call typically specifies only one of these at a time. + + +The final arguments are pointers to arrays that will be filled +in and returned by the name server. The name server will allocate and +return arrays filled with the classes, names, and methods of all XPA +access points that match the template +and have the specified type. Also returned are info strings, which +generally are used internally by the client routines. These can be +ignored (but the strings must be freed). The function returns the +number of matches. The returned value can be used to loop through the +matches: + +B<Example:> + + #include <xpa.h> + + char **classes; + char **names; + char **methods; + char **infos; + int i, n; + n = XPANSLookup(NULL, "foo*", "g", &classes, &names, &methods, &infos); + for(i=0; i<n; i++){ + [more specific checks on possibilities ...] + [perhaps a call to XPAGet for those that pass, etc. ...] + /* don't forget to free alloc'ed strings when done */ + free(classes[i]); + free(names[i]); + free(methods[i]); + free(infos[i]); + } + /* free up arrays alloc'ed by names server */ + if( n > 0 ){ + free(classes); + free(names); + free(methods); + free(infos); + } + + +The specified +template +also can be a host:port specification, for example: + + myhost:12345 + + +In this case, no connection is made to the name server. Instead, the +call will return one entry such that the ip array contains the ip for +the specified host and the port array contains the port. The class +and name entries are set to the character "?", since the class and +name of the access point are not known. + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpaoom.pod b/xpa/doc/pod/xpaoom.pod new file mode 100644 index 0000000..b8b2431 --- /dev/null +++ b/xpa/doc/pod/xpaoom.pod @@ -0,0 +1,60 @@ +=pod + +=head1 NAME + + + +B<Xpaoom: What happens when XPA runs out of memory?> + + + +=head1 SYNOPSIS + + + + + +When XPA can't allocate memory, it exits. You can arrange to have it call +longjmp() instead. + + + +=head1 DESCRIPTION + + + + + +When an XPA server or client cannot allocate memory, it will attempt to +output an error message and then exit. If this is not satisfactory (e.g., +perhaps your program is interactive and can recover from OOM errors), you +can tell XPA to call longjmp() to go to a recovery branch. To pass the +requisite jmp_buf variable to XPA, make the following call: + + XPASaveJmp(void *env); + +The value of env is the address of a jmp_buf variable that was previously +passed to setjmp(). For example: + + jmp_buf env; + ... + if( setjmp(jmp_buf) != 0 ){ + /* out of memory -- take corrective action, if possible */ + } else { + /* save env for XPA */ + XPASaveJmp((void *)&jmp_buf); + } + // enter main loop ... + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpaopen.pod b/xpa/doc/pod/xpaopen.pod new file mode 100644 index 0000000..d88df02 --- /dev/null +++ b/xpa/doc/pod/xpaopen.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + + + +B<XPAOpen: allocate a persistent client handle> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + XPA XPAOpen(char *mode); + + + + + +=head1 DESCRIPTION + + + + +XPAOpen() allocates a persistent XPA struct that can be used with +calls to XPAGet(), XPASet(), XPAInfo(), XPAGetFd(), and +XPASetFd(). Persistence means that a connection to an XPA server is +not closed when one of the above calls is completed but will be +re-used on successive calls. Using XPAOpen() therefore saves the time +it takes to connect to a server, which could be significant with slow +connections or if there will be a large number of exchanges with a +given access point. The mode argument currently is ignored ("reserved +for future use"). + + +An XPA struct is returned if XPAOpen() was successful; otherwise NULL +is returned. This returned struct can be passed as the first argument +to XPAGet(), etc. Those calls will update the list of active XPA +connections. Already connected servers (from a previous call) are +left connected and new servers also will be connected. Old servers +(from a previous call) that are no longer needed are disconnected. +The connected servers will remain connected when the next call to +XPAGet() is made and connections are once again updated. + + +B<Example:> + + #include <xpa.h> + + XPA xpa; + xpa = XPAOpen(NULL); + + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpapoll.pod b/xpa/doc/pod/xpapoll.pod new file mode 100644 index 0000000..1f26ee1 --- /dev/null +++ b/xpa/doc/pod/xpapoll.pod @@ -0,0 +1,58 @@ +=pod + +=head1 NAME + + + +B<XPAPoll: execute existing XPA requests> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + int XPAPoll(int msec, int maxreq); + + + + + +=head1 DESCRIPTION + + + + +It is sometimes desirable to implement a polling loop, i.e., where one +checks for and processes XPA requests without blocking. For this +situation, use the XPAPoll() routine: + + XPAPoll(int msec, int maxreq); + + +The XPAPoll() routine will perform XPAAddSelect() and select(), but with a +timeout specified in millisecs by the msec argument. If one or more +XPA requests are made before the timeout expires, the XPAProcessSelect() +routine is called to process those requests. The maxreq value determines +how many requests will be processed: if maxreq < 0, then no events are +processed, but instead, the return value indicates the number of events +that are pending. If maxreq == 0, then all currently pending requests +will be processed. Otherwise, up to maxreq requests will be processed. +(The most usual values for maxreq are 0 to process all requests and 1 +to process one request). + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xparace.pod b/xpa/doc/pod/xparace.pod new file mode 100644 index 0000000..418b8a0 --- /dev/null +++ b/xpa/doc/pod/xparace.pod @@ -0,0 +1,89 @@ +=pod + +=head1 NAME + + + +B<XPA Race Conditions> + + + +=head1 SYNOPSIS + + + +Potential XPA race conditions and how to avoid them. + + + +=head1 DESCRIPTION + + + + +Currently, there is only one known circumstance in which XPA can get +(temporarily) deadlocked in a race condition: if two or more XPA +servers send messages to one another using an XPA client routine such +as XPASet(), they can deadlock while each waits for the other server +to respond. (This can happen if the servers call XPAPoll() with a +time limit, and send messages in between the polling call.) The +reason this happens is that both client routines send a string to the +other server to establish the handshake and then wait for the server +response. Since each client is waiting for a response, neither is able +to enter its event-handling loop and respond to the other's +request. This deadlock will continue until one of the timeout periods +expire, at which point an error condition will be triggered and the +timed-out server will return to its event loop. + + +Starting with version 2.1.6, this rare race condition can be +avoided by setting the XPA_IOCALLSXPA environment variable for servers +that will make client calls. Setting this variable causes all XPA +socket IO calls to process outstanding XPA requests whenever the +primary socket is not ready for IO. This means that a server making a +client call will (recursively) process incoming server requests while +waiting for client completion. It also means that a server callback +routine can handle incoming XPA messages if it makes its own XPA call. +The semi-public routine oldvalue=XPAIOCallsXPA(newvalue) can be used +to turn this behavior off and on temporarily. Passing a 0 will turn +off IO processing, 1 will turn it back on. The old value is returned +by the call. + + +By default, the XPA_IOCALLSXPA option is turned off, because we judge +that the added code complication and overhead involved will not be +justified by the amount of its use. Moreover, processing XPA requests +within socket IO can lead to non-intuitive results, since incoming +server requests will not necessarily be processed to completion in the +order in which they are received. + + +Aside from setting XPA_IOCALLSXPA, the simplest way to avoid this race +condition is to multi-process: when you want to send a client message, +simply start a separate process to call the client routine, so that +the server is not stopped. It probably is fastest and easiest to use +fork() and then have the child call the client routine and exit. But +you also can use either the system() or popen() routine to start one +of the command line programs and do the same thing. Alternatively, you +can use XPA's internal launch() routine instead of system(). Based on +fork() and exec(), this routine is more secure than system() because +it does not call /bin/sh. + + +Starting with version 2.1.5, you also can send an XPAInfo() message with +the mode string "ack=false". This will cause the client to send a message +to the server and then exit without waiting for any return message from +the server. This UDP-like behavior will avoid the server deadlock when +sending short XPAInfo messages. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpaserver.pod b/xpa/doc/pod/xpaserver.pod new file mode 100644 index 0000000..275defd --- /dev/null +++ b/xpa/doc/pod/xpaserver.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + + + +B<XPAServer: The XPA Server-side Programming Interface> + + + +=head1 SYNOPSIS + + + + +A description of the XPA server-side programming interface. + + + +=head1 DESCRIPTION + + + +B<Introduction to XPA Server Programming> + +Creating an XPA server is easy: you generally only need to call the +XPANew() subroutine to define a named XPA access point and set up the +send and receive callback routines. You then enter an event loop such +as XPAMainLoop() to field XPA requests. + + #include <xpa.h> + + XPA XPANew(char *class, char *name, char *help, + int (*send_callback)(), void *send_data, char *send_mode, + int (*rec_callback)(), void *rec_data, char *rec_mode); + + XPA XPACmdNew(char *class, char *name); + + XPACmd XPACmdAdd(XPA xpa, + char *name, char *help, + int (*send_callback)(), void *send_data, char *send_mode, + int (*rec_callback)(), void *rec_data, char *rec_mode); + + void XPACmdDel(XPA xpa, XPACmd cmd); + + XPA XPAInfoNew(char *class, char *name, + int (*info_callback)(), void *info_data, char *info_mode); + + int XPAFree(XPA xpa); + + void XPAMainLoop(void); + + int XPAPoll(int msec, int maxreq); + + void XPAAtExit(void); + + void XPACleanup(void); + + + +B<Introduction> + +To use the XPA application programming interface, a software developer +generally will include the xpa.h definitions file: + + #include <xpa.h> + +in the software module that defines or accesses an XPA access point, and +then will link against the libxpa.a library: + + gcc -o foo foo.c libxpa.a + +XPA has been compiled using both C and C++ compilers. + + +A server program generally defines an XPA access point by calling the +XPANew() routine and specifies "send" and/or "receive" callback +procedures to be executed by the program when an external process +either sends data or commands to this access point or requests data or +information from this access point. A program also can define several +sub-commands for a single access point by calling XPACmdNew() and +XPACmdAdd() instead. Having defined one or more public access points +in this way, an XPA server program enters its usual event loop (or +uses the standard XPA event loop). + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpaset.pod b/xpa/doc/pod/xpaset.pod new file mode 100644 index 0000000..19c2dbe --- /dev/null +++ b/xpa/doc/pod/xpaset.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + + + +B<xpaset: send data to one or more XPA servers> + + + +=head1 SYNOPSIS + + + + + +<data> | xpaset [-h] [-i nsinet] [-m method] [-n] [-p] [-s] [-t sval,lval] [-u users] [-v] <template|host:port> [paramlist] + + + + + +=head1 OPTIONS + + + + + + -h print help message + -i access XPA point on different machine (override XPA_NSINET) + -m override XPA_METHOD environment variable + -n don't wait for the status message after server completes + -p don't read (or send) buf data from stdin + -s enter server mode + -t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) + -u [users] XPA points can be from specified users (override XPA_NSUSERS) + -v verify message to stdout + --version display version and exit + + + + +=head1 DESCRIPTION + + + + +Data read from stdin will be sent to access points matching the +template +or host:port. +A set of qualifying parameters can be appended. + +Normally, xpaset reads data input from stdin until EOF and sends those +data to the XPA target, along with parameters entered on the command +line. For example to send a FITS file to the ds9 image display: + + cat foo.fits | xpaset ds9 fits + + +Sometimes, however, it is desirable to send only parameters to an XPA +access point, without sending data. For such cases, use the -p switch to +indicate that there is no data being send to stdin. For example, to +change the colormap used by the ds9 image display program, use: + + csh> xpaset -p ds9 cmap Heat + +Of course, this also can be accomplished by sending EOF to stdin in +any of the usual ways: + + csh> echo "" | xpaset ds9 cmap Heat + csh> xpaget ds9 cmap Heat < /dev/null + csh> xpaset ds9 cmap Heat + ^D # Ctl-D signals EOF + + +The -s switch puts xpaset into server mode, in which commands and data +can be sent to access points without having to run xpaset multiple times. +(Its not clear if this buys you much!) The syntax for sending commands +in server mode is: + + + csh> xpaset -s + xpaset ds9 colormap I8 + ^D + xpaset ds9 regions + circle 200 300 40 + circle 300 400 50 + ^D +etc. + +After the required "xpaset" command is specified, optional ASCII data +can be appended (as in the region example). A single data/command set is +delimited by ^D. Note that typing ^D when a command is expected terminates +the program. + +NB: server mode only works from the terminal and only ASCII data can be +sent in this way. + +B<Examples:> + + csh> xpaset ds9 file < foo.fits + csh> echo "stop" | xpaset myhost:12345 + + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpasetfd.pod b/xpa/doc/pod/xpasetfd.pod new file mode 100644 index 0000000..6a49684 --- /dev/null +++ b/xpa/doc/pod/xpasetfd.pod @@ -0,0 +1,113 @@ +=pod + +=head1 NAME + + + +B<XPASetFd: send data from stdin to one or more XPA servers> + + + +=head1 SYNOPSIS + + + + + + #include <xpa.h> + + int XPASetFd(XPA xpa, + char *template, char *paramlist, char *mode, + int fd, char **names, char **messages, int n) + + + + + +=head1 DESCRIPTION + + + + +Read data from a standard I/O fd and send it to one or more XPA +servers whose class:name identifier matches the specified +template. + + +A +template +of the form "class1:name1" is sent to the +XPA name server, which returns a list of at most n matching XPA +servers. A connection is established with each of these servers and +the paramlist string is passed to the server as the data transfer +request is initiated. If an XPA struct is passed to the call, then the +persistent connections are updated as described above. Otherwise, +temporary connections are made to the servers (which will be closed +when the call completes). + + +The XPASetFd() routine then reads bytes from the specified fd +until EOF and sends these bytes to the XPA servers. +The final parameter n specifies the maximum number of servers to contact. +A string containing the class:name and ip:port of each server is returned in +the name array. If a given server returned an error, then the error +message will be stored in the associated element of the messages array. +NB: if specified, the name and messages arrays must be of size n or greater. + + +The return value will contain the actual number of servers that were +processed. This value thus will hold the number of valid entries in +the names and messages arrays, and can be used to loop through these +arrays. In names and/or messages is NULL, no information is passed back +in that array. + + +The mode string is of the form: "key1=value1,key2=value2,..." +The following keywords are recognized: + + key value default explanation + ------ -------- -------- ----------- + ack true/false true if false, don't wait for ack from server (after callback completes) + verify true/false false send buf from XPASet[Fd] to stdout + + +The ack keyword is useful in cases where one does not want to wait for +the server to complete, e.g. is a lot of processing needs to be done +on the passed data or when the success of the server operation is not +relevant to the client. + + +B<Example:> + + #include <xpa.h> + + #define NXPA 10 + int i, got; + int fd; + char *names[NXPA]; + char *messages[NXPA]; + fd = open(...); + got = XPASetFd(NULL, "ds9", "fits", NULL, fd, names, messages, NXPA); + for(i=0; i<got; i++){ + if( messages[i] != NULL ){ + /* error processing */ + fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]); + } + if( names[i] ) + free(names[i]); + if( messages[i] ) + free(messages[i]); + } + + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + +=cut diff --git a/xpa/doc/pod/xpatcl.pod b/xpa/doc/pod/xpatcl.pod new file mode 100644 index 0000000..008a4f3 --- /dev/null +++ b/xpa/doc/pod/xpatcl.pod @@ -0,0 +1,258 @@ +=pod + +=head1 NAME + + + +B<XPATcl: the XPA Interface to the Tcl/Tk Environment> + + + +=head1 SYNOPSIS + + + + + + +Tcl/Tk programs can act as XPA clients and/or servers using the Tcl +interface to XPA that is contained in the libtclxpa.so shared object. + +B<Server Routines> + + + set xpa [xpanew class name help sproc sdata smode rproc rdata rmode] + xpafree xpa + set xpa [xpanew class name help iproc idata imode] + set xpa [xpacmdnew class name] + xpacmdadd xpa name help sproc sdata smode rproc rdata rmode + xpacmddel xpa cmd + set val [xparec xpa option] + options: name, class, method, cmdfd, datafd, cmdchan, datachan + xpasetbuf xpa buf len + xpaerror xpa message + xpamessage xpa message + + +B<Client Routines> + + + set xpa [xpaopen mode] + xpaclose xpa + set got [xpaget xpa template paramlist mode bufs lens names errs n] + set got [xpaget xpa template paramlist mode chans names errs n] + set got [xpaset xpa template paramlist mode buf len names errs n] + set got [xpasetfd xpa template paramlist mode chan names errs n] + set got [xpainfo xpa template paramlist mode names errs n] + # NB: 2.1 calling sequence change + # set got [xpaaccess template type] (2.0.5) + set got [xpaaccess xpa template paramlist mode names errs n] + set got [xpanslookup template type classes names methods] + + + + +=head1 DESCRIPTION + + + + + +You can call XPANew(), XPACmdNew(), or XPAInfoNew() within a C +routine to add C-based XPA server callbacks to a TCL/Tk program that +uses a Tcl/Tk event loop (either vwait() or the Tk event loop); +Such a program does not need or want to use the XPA event loop. +Therefore, in order to add XPA access points to the Tcl/Tk loop, the +following routine should be called beforehand: + + int XPATclAddInput(XPA xpa); + + +Normally, the xpa argument is NULL, meaning that all current XPA +access points are registered with the event loop. However, if a +single XPA access point is to be added (i.e., after the event loop is +started) then the handle of that XPA access point can be passed to +this routine. + + +The significance of the XPA/TCL interface goes beyond the support for +using XPA inside C code. The interface allows you to write XPA +servers and to make calls to the XPA client interface within the Tcl +environment using the Tcl language directly. The XPA/Tcl +interface can be loaded using the following package command: + + package require tclxpa 2.0 + +Alternatively, you can load the shared object (called libtclxpa.so ) directly: + + load .../libtclxpa.so tclxpa + + +Once the tclxpa package is loaded, you can use Tcl versions of XPA +routines to define XPA servers or make client XPA calls. The +interface for these routines is designed to match the Unix XPA +interface as nearly as possible. Please refer to +XPA Servers +and +XPA Clients +for general information about these routines. + + +The file test.tcl in the XPA source directory gives examples for using the +XPA/Tcl interface. + + +The following notes describe the minor differences between the interfaces. + +B<XPANew> + + + set xpa [xpanew class name help sproc sdata smode rproc rdata rmode] + + + +rproc and sproc routines are routines. The calling sequence of the +rproc routine is identical to its C counterpart: + + proc rec_cb { xpa client_data paramlist buf len } { ... } + + +The sproc routine, however is slightly different from its C counterpart +because of the difficulty of passing data back from the callback to C: + + proc sendcb { xpa client_data paramlist } { ... } + + +Note that the C-based server's char **buf and int *len arguments are +missing from the Tcl callback. This is because we did not know how to +fill buf with data and pass it back to the C routines for communication +with the client. Instead, the Tcl server callback uses the following +routine to set buf and len: + + xpasetbuf xpa buf len + +where: + + arg explanation + ------ ----------- + xpa the first argument of the server callback + buf the data to be returned to the client + len data length in bytes, (if absent, use length of the buf object) + + +When this routine is called, a copy of buf is saved for transmission to +the client. + + +The fact that buf is duplicated means that TCL server writers might wish to +perform the I/O directly within the callback, rather than have XPA do it +automatically at the end of the routine. To do this, set: + + fillbuf=false + + +in the xpanew smode and then perform I/O through the Tcl channel +obtained from: + + set dchan [xparec $xpa datachan] + + +where: + + arg explanation + ------ ----------- + xpa the first argument of the server callback + datachan literal string "datachan" that returns the data channel + len data length in bytes, (if absent, use length of the buf object) + + + +NB: datachan and cmdchan are not available under Windows. It is +necessary to use the "raw" equivalents: datafd and cmdfd. + + + +The same considerations apply to the rproc for receive servers: a copy +of the incoming data is generated to pass to the receive callback. This +copy again can be avoided by using "fillbuf=false" in the rmode and then +reading the incoming data from datachan. + + +The send and receive callback routines can use the xpaerror and xpamessage +routines to send errors and messages back to the client. If you also +want tcl itself to field an error condition, use the standard return call: + + return ?-code c? ?-errorinfo i? ?-errorcode ec? string + + +See the Tcl man page for more info. + +B<XPARec> + +The Tcl xparec procedure supplies server routines with access to information +that is available via macros in the C interface: + + set val [xparec xpa <option>] + + +where option is: name, class, method, cmdfd, datafd, cmdchan, +datachan. Note that two additional identifiers, cmdchan and datachan, +have been added to to provide Tcl channels corresponding to datafd and +cmdfd. (These latter might still be retrieved in Tcl and passed back +to a C routines.) An additional option called "version" can be used to +determine the XPA version used to build the Tcl interface. Note that +the standard options require a valid XPA handle, but "version" does +not (since it simply reports the value of the XPA_VERSION definition +in the XPA source include file). + + + +NB: datachan and cmdchan are not available under Windows. It is +necessary to use the "raw" equivalents: datafd and cmdfd. + + + macro explanation + ------ ----------- + class class of this xpa + name name of this xpa + method method string (inet or local connect info) + cmdchan Tcl channel of command socket + datachan Tcl channel of data socket + cmdfd fd of command socket + datafd fd of data socket + sendian endian-ness of server ("little" or "big") + cendian endian-ness of client ("little" or "big" + version XPA version used to build this code + + + +Under Windows, the Tcl event handler cannot automatically sense when an +XPA socket is ready for IO (i.e. Tcl_CreateFileHandler() is not available +under Windows). The Windows Tcl event handler therefore must be awakened +occasionally for check for XPA events. This is done using the standard +Tcl_SetMaxBlockTime() call. The time parameter is defined in tclloop.c +and is currently set to 1000 microseconds (1/1000 of a second). + + +The version option can be used to differentiate between source code versions. +It was created to support legacy Tcl code that needs to maintain the 2.0.5 +calling sequence for xpaaccess. You can use a version test such as: + + if [catch { xparec "" version } version] { + puts "pre-2.1.0e" + } else { + puts [split $version .] + } + + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpatemplate.pod b/xpa/doc/pod/xpatemplate.pod new file mode 100644 index 0000000..1524934 --- /dev/null +++ b/xpa/doc/pod/xpatemplate.pod @@ -0,0 +1,120 @@ +=pod + +=head1 NAME + + + +B<XPATemplate: Access Point Names and Templates> + + +=head1 SYNOPSIS + + + + + +XPA access points are composed of two parts: a general class and a +specific name. Both parts accept template characters so that you +can send/retrieve data to/from multiple servers at one time. + + + +=head1 DESCRIPTION + + + + + +When XPA servers call +XPANew(), +or +XPACmdNew() +to define XPA access points, they specify a string identifier composed of a +class and a name. When clients communicate with XPA access points, +they specify which access points to communicate with using +an identifier of the form: + + class:name + +All registered XPA access points that match the specified identifier +will be available for communication (subject to access control rules, +etc.) + + +As of XPA 2.1.5, the length of both the class and name designations are +limited to 1024 characters. + + +The XPA class:name identifier actually is a template: it accepts wild +cards in its syntax, so a single specifier can match more than one XPA +access point. (Note that the class is optional and defaults to "*".) +The allowed syntax for clients to specify the class:name template is +of the form shown below. (Note that "*" is used to denote a generic +wild card, but other wild cards characters are supported, as described +below). + + template explanation + -------- ----------- + class:name exact match of class and name + name match any class with this name + *:name match any class with this name + class:* match any name of this class + *:* match any access point + + +In general, the following wild-cards can be applied to class and name: + + wildcard explanation + -------- ----------- + ? match any character, but there must be one + * match anything, or nothing + [...] match an inclusive set + + +Although the class:name template normally is used to refer to XPA +access points, these also can be specified using their individual +socket identifiers. For inet sockets, the socket identifier is +B<ip:port>, where ip can be the DNS-registered name, +the ASCII IP number (e.g. 123.45.67.890) or the hex IP number +(e.g. 838f3a60). For unix sockets, the identifier is the socket file +name. These socket identifiers are displayed as the fourth argument +in the xpans display of registered access points. For example, +consider the ds9 program started using inet sockets. The xpans name +server will register something like this: + + csh> xpaget xpans + DS9 ds9 gs saord.harvard.edu:3236 eric + +You can access ds9 using ip:3236 in any of the three forms: + + csh> xpaget saord:3236 file + /home/eric/data/snr.ev + + csh> xpaget 123.45.67.890:3236 file + /home/eric/data/snr.ev + + csh> xpaget 838f3a60:3236 file + /home/eric/data/snr.ev + +In the case of unix sockets, the socket identifier is a file: + + csh> xpaget xpans + DS9 ds9 gs /tmp/.xpa/DS9_ds9.2631 eric + + csh> xpaget /tmp/.xpa/DS9_ds9.2631 file + /home/eric/data/snr.ev + +This feature can be useful in distinguishing between multiple +instances of a program that all have the same class:name designation. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpausers.pod b/xpa/doc/pod/xpausers.pod new file mode 100644 index 0000000..4c3353b --- /dev/null +++ b/xpa/doc/pod/xpausers.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + + + +B<XPAUsers: Distinguishing Users> + + + +=head1 SYNOPSIS + + + + + +XPA normally distinguishes between users on a given host, but it is possible +to send data to access points belonging to other users. + + + +=head1 DESCRIPTION + + + + + +A single XPA name service typically serves all users on a given +machine. Two users can register the same XPA access points on the +same machine without conflict, because the user's username is +registered with each access point and, by default, programs such as +xpaget and xpaset only process access points of the appropriate user. +For example: + + XPA xpa1 gs 838e2f67:1262 eric + XPA xpa2 gs 838e2f67:1266 eric + XPA xpa1 gs 838e2f67:2523 john + XPA xpa2 gs 838e2f67:2527 john + +Here the users "eric" and "john" both have registered the access +points xpa1 and xpa2. When either "john" or "eric" retrieves +information from xpa1, they will process only the access point +registered in their user name. + + +If you want to access another user's XPA access points on a single +machine, use the -u [user] option on xpaset, xpaget, etc. For example, +if eric executes: + + xpaget -u john xpa1 + +he will access John's xpa1 access point.Use "*" to access all users +on a given machine: + + xpaget -u "*" xpa1 + +Note that the XPA Environment Variable +XPA_NSUSERS can be used to specify the default list of users to +process: + + setenv XPA_NSUSERS "eric,john" + +will cause access points from both "eric" and "john" to be processed +by default. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut diff --git a/xpa/doc/pod/xpaxt.pod b/xpa/doc/pod/xpaxt.pod new file mode 100644 index 0000000..34e1049 --- /dev/null +++ b/xpa/doc/pod/xpaxt.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + + + +B<XPAXt: the XPA Interface to Xt (X Windows)> + + + +=head1 SYNOPSIS + + + + +Describes how XPA access points can be added to X Toolkit (Xt) programs. + + + +=head1 DESCRIPTION + + + + + +XPA supports Xt programs: you can call XPANew(), XPACmdNew(), or +XPAInfoNew() within any C routine to add XPA server callbacks to an Xt +program. Since an Xt program has its own event loop call (i.e., +XtAppMainLoop()), it therefore does not need or want to use the XPA +even loop. Thus, in order to add XPA access points to the standard Xt +event loop, the following routine should be called before entering the +loop: + + int XPAXtAddInput(XtAppContext app, XPA xpa) + + +The XPAAddAddInput() routine will add XPA access points to the Xt event +loop by making calls to the standard XtAppAddInput() routine. (If the +XtAppContext argument is NULL, then the alternate XtAddInput() routine +is used instead.) If the xpa argument is NULL, then all active XPA +access points are added to the loop. If xpa is not NULL, then only +the specified access point is added. The latter type of call is used +to add new access points from within a callback, after the program has +entered the XtAppMainLoop() even loop. + + + +=head1 SEE ALSO + + + +See xpa(n) for a list of XPA help pages + + + +=cut |