diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2018-01-23 16:53:51 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2018-01-23 16:53:51 (GMT) |
| commit | 51e1f85047b34f095ed69a3024d696997d2667c8 (patch) | |
| tree | a8d46838982aa78a35653c10d0b7370d751d6181 /xpa/doc/pod | |
| parent | 0c198f7902ee997dd8ec3631e8ff1c385257014d (diff) | |
| download | blt-51e1f85047b34f095ed69a3024d696997d2667c8.zip blt-51e1f85047b34f095ed69a3024d696997d2667c8.tar.gz blt-51e1f85047b34f095ed69a3024d696997d2667c8.tar.bz2 | |
upgrade xpa
Diffstat (limited to 'xpa/doc/pod')
41 files changed, 0 insertions, 5405 deletions
diff --git a/xpa/doc/pod/xpa.pod b/xpa/doc/pod/xpa.pod deleted file mode 100644 index 7787d4b..0000000 --- a/xpa/doc/pod/xpa.pod +++ /dev/null @@ -1,399 +0,0 @@ -=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 deleted file mode 100644 index ab34b9b..0000000 --- a/xpa/doc/pod/xpaaccess.pod +++ /dev/null @@ -1,102 +0,0 @@ -=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 deleted file mode 100644 index 3be9d4c..0000000 --- a/xpa/doc/pod/xpaacl.pod +++ /dev/null @@ -1,145 +0,0 @@ -=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 deleted file mode 100644 index 4310835..0000000 --- a/xpa/doc/pod/xpaatexit.pod +++ /dev/null @@ -1,41 +0,0 @@ -=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 deleted file mode 100644 index bce7be0..0000000 --- a/xpa/doc/pod/xpachanges.pod +++ /dev/null @@ -1,102 +0,0 @@ -=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 deleted file mode 100644 index 2d55e5a..0000000 --- a/xpa/doc/pod/xpacleanup.pod +++ /dev/null @@ -1,47 +0,0 @@ -=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 deleted file mode 100644 index 858a8a8..0000000 --- a/xpa/doc/pod/xpaclient.pod +++ /dev/null @@ -1,95 +0,0 @@ -=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 deleted file mode 100644 index 7148752..0000000 --- a/xpa/doc/pod/xpaclose.pod +++ /dev/null @@ -1,53 +0,0 @@ -=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 deleted file mode 100644 index 31859e5..0000000 --- a/xpa/doc/pod/xpacmdadd.pod +++ /dev/null @@ -1,69 +0,0 @@ -=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 deleted file mode 100644 index 95c545d..0000000 --- a/xpa/doc/pod/xpacmddel.pod +++ /dev/null @@ -1,43 +0,0 @@ -=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 deleted file mode 100644 index 429972b..0000000 --- a/xpa/doc/pod/xpacmdnew.pod +++ /dev/null @@ -1,90 +0,0 @@ -=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 deleted file mode 100644 index c5ea647..0000000 --- a/xpa/doc/pod/xpacode.pod +++ /dev/null @@ -1,73 +0,0 @@ -=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 deleted file mode 100644 index 9fc9746..0000000 --- a/xpa/doc/pod/xpacommon.pod +++ /dev/null @@ -1,266 +0,0 @@ -=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 deleted file mode 100644 index 75597a7..0000000 --- a/xpa/doc/pod/xpaconvert.pod +++ /dev/null @@ -1,202 +0,0 @@ -=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 deleted file mode 100644 index a1d095f..0000000 --- a/xpa/doc/pod/xpaenv.pod +++ /dev/null @@ -1,517 +0,0 @@ -=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 deleted file mode 100644 index 4071fb2..0000000 --- a/xpa/doc/pod/xpafree.pod +++ /dev/null @@ -1,49 +0,0 @@ -=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 deleted file mode 100644 index 77e771b..0000000 --- a/xpa/doc/pod/xpaget.pod +++ /dev/null @@ -1,67 +0,0 @@ -=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 deleted file mode 100644 index 5be9cfc..0000000 --- a/xpa/doc/pod/xpagetfd.pod +++ /dev/null @@ -1,133 +0,0 @@ -=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 deleted file mode 100644 index 40793a0..0000000 --- a/xpa/doc/pod/xpainet.pod +++ /dev/null @@ -1,285 +0,0 @@ -=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 deleted file mode 100644 index 65fdb3e..0000000 --- a/xpa/doc/pod/xpainfo.pod +++ /dev/null @@ -1,66 +0,0 @@ -=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 deleted file mode 100644 index ae54f54..0000000 --- a/xpa/doc/pod/xpainfonew.pod +++ /dev/null @@ -1,92 +0,0 @@ -=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 deleted file mode 100644 index 31ce14f..0000000 --- a/xpa/doc/pod/xpaintro.pod +++ /dev/null @@ -1,176 +0,0 @@ -=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 deleted file mode 100644 index 786e04b..0000000 --- a/xpa/doc/pod/xpamacros.pod +++ /dev/null @@ -1,76 +0,0 @@ -=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 deleted file mode 100644 index 4fabf8e..0000000 --- a/xpa/doc/pod/xpamainloop.pod +++ /dev/null @@ -1,108 +0,0 @@ -=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 deleted file mode 100644 index fb8ef7c..0000000 --- a/xpa/doc/pod/xpamb.pod +++ /dev/null @@ -1,249 +0,0 @@ -=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 deleted file mode 100644 index 038ac4e..0000000 --- a/xpa/doc/pod/xpamethod.pod +++ /dev/null @@ -1,99 +0,0 @@ -=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 deleted file mode 100644 index 7c0ea8d..0000000 --- a/xpa/doc/pod/xpaname.pod +++ /dev/null @@ -1,56 +0,0 @@ -=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 deleted file mode 100644 index 1a3800f..0000000 --- a/xpa/doc/pod/xpanew.pod +++ /dev/null @@ -1,243 +0,0 @@ -=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 deleted file mode 100644 index 071dd68..0000000 --- a/xpa/doc/pod/xpans.pod +++ /dev/null @@ -1,226 +0,0 @@ -=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 deleted file mode 100644 index e0f4cdc..0000000 --- a/xpa/doc/pod/xpanslookup.pod +++ /dev/null @@ -1,126 +0,0 @@ -=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 deleted file mode 100644 index b8b2431..0000000 --- a/xpa/doc/pod/xpaoom.pod +++ /dev/null @@ -1,60 +0,0 @@ -=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 deleted file mode 100644 index d88df02..0000000 --- a/xpa/doc/pod/xpaopen.pod +++ /dev/null @@ -1,69 +0,0 @@ -=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 deleted file mode 100644 index 1f26ee1..0000000 --- a/xpa/doc/pod/xpapoll.pod +++ /dev/null @@ -1,58 +0,0 @@ -=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 deleted file mode 100644 index 418b8a0..0000000 --- a/xpa/doc/pod/xparace.pod +++ /dev/null @@ -1,89 +0,0 @@ -=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 deleted file mode 100644 index 275defd..0000000 --- a/xpa/doc/pod/xpaserver.pod +++ /dev/null @@ -1,96 +0,0 @@ -=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 deleted file mode 100644 index 19c2dbe..0000000 --- a/xpa/doc/pod/xpaset.pod +++ /dev/null @@ -1,115 +0,0 @@ -=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 deleted file mode 100644 index 6a49684..0000000 --- a/xpa/doc/pod/xpasetfd.pod +++ /dev/null @@ -1,113 +0,0 @@ -=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 deleted file mode 100644 index 008a4f3..0000000 --- a/xpa/doc/pod/xpatcl.pod +++ /dev/null @@ -1,258 +0,0 @@ -=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 deleted file mode 100644 index 1524934..0000000 --- a/xpa/doc/pod/xpatemplate.pod +++ /dev/null @@ -1,120 +0,0 @@ -=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 deleted file mode 100644 index 4c3353b..0000000 --- a/xpa/doc/pod/xpausers.pod +++ /dev/null @@ -1,76 +0,0 @@ -=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 deleted file mode 100644 index 34e1049..0000000 --- a/xpa/doc/pod/xpaxt.pod +++ /dev/null @@ -1,56 +0,0 @@ -=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 |