diff options
Diffstat (limited to 'xpa/man/mann')
| -rw-r--r-- | xpa/man/mann/xpa.n | 318 | ||||
| -rw-r--r-- | xpa/man/mann/xpaacl.n | 251 | ||||
| -rw-r--r-- | xpa/man/mann/xpacode.n | 181 | ||||
| -rw-r--r-- | xpa/man/mann/xpacommon.n | 302 | ||||
| -rw-r--r-- | xpa/man/mann/xpaconvert.n | 267 | ||||
| -rw-r--r-- | xpa/man/mann/xpaenv.n | 482 | ||||
| -rw-r--r-- | xpa/man/mann/xpainet.n | 396 | ||||
| -rw-r--r-- | xpa/man/mann/xpaintro.n | 250 | ||||
| -rw-r--r-- | xpa/man/mann/xpamethod.n | 200 | ||||
| -rw-r--r-- | xpa/man/mann/xpaname.n | 158 | ||||
| -rw-r--r-- | xpa/man/mann/xpaoom.n | 166 | ||||
| -rw-r--r-- | xpa/man/mann/xpatcl.n | 362 | ||||
| -rw-r--r-- | xpa/man/mann/xpatemplate.n | 232 | ||||
| -rw-r--r-- | xpa/man/mann/xpausers.n | 186 | ||||
| -rw-r--r-- | xpa/man/mann/xpaxt.n | 161 |
15 files changed, 3912 insertions, 0 deletions
diff --git a/xpa/man/mann/xpa.n b/xpa/man/mann/xpa.n new file mode 100644 index 0000000..189a601 --- /dev/null +++ b/xpa/man/mann/xpa.n @@ -0,0 +1,318 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpa n" +.TH xpa n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fB\s-1XPA:\s0 Public Access to Data and Algorithms\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +This document is the Table of Contents for \s-1XPA\s0. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1XPA\s0 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 \s-1XPA\s0 client commands in the shell or by utilizing +such commands in scripts. Because \s-1XPA\s0 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 \s-1XPA\s0 services, and +client access can be extended or modified easily at any time. +.PP +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 \s-1TCP\s0 sockets as a +transport mechanism, \s-1XPA\s0 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 \s-1XPA\s0 servers +across a network. +.PP +\&\s-1XPA\s0 implements a layered interface that is designed to be useful both +to software developers and to users. The interface consists of a +library of \s-1XPA\s0 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 \s-1XPA\s0 library, access points can be added to Tcl/Tk programs, +Xt programs, or to Unix programs that use the \s-1XPA\s0 event loop or any +event loop based on \fIselect()\fR. 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. +.PP +Choose from the following topics: +.IP "\(bu" 4 +Introduction to \s-1XPA\s0 +[xpaintro(n)] +.IP "\(bu" 4 +Access Point Names and Templates +[xpatemplate(n)] +.IP "\(bu" 4 +Getting Common Information About Access Points +[xpacommon(n)] +.IP "\(bu" 4 +Communication Methods +[xpamethod(n)] +.IP "\(bu" 4 +Communication Between Hosts +[xpainet(n)] +.IP "\(bu" 4 +Distinguishing Users +[xpausers(n)] +.IP "\(bu" 4 +\&\s-1XPA\s0 User Programs +.RS 4 +.IP "\(bu" 4 +xpaget: get data and info +[\fIxpaget\fR\|(1)] +.IP "\(bu" 4 +xpaset: send data and info +[\fIxpaset\fR\|(1)] +.IP "\(bu" 4 +xpainfo: send info alert +[\fIxpainfo\fR\|(1)] +.IP "\(bu" 4 +xpaaccess: get access point info +[\fIxpaaccess\fR\|(1)] +.IP "\(bu" 4 +xpamb: message bus emulation +[\fIxpamb\fR\|(1)] +.IP "\(bu" 4 +xpans: the \s-1XPA\s0 name server +[\fIxpans\fR\|(1)] +.RE +.RS 4 +.RE +.IP "\(bu" 4 +\&\s-1XPA\s0 Server Routines +.RS 4 +.IP "\(bu" 4 +XPANew: define a new access point +[\fIxpanew\fR\|(3)] +.IP "\(bu" 4 +XPACmdNew: define a new command access point +[\fIxpacmdnew\fR\|(3)] +.IP "\(bu" 4 +XPACmdAdd: add a command +[\fIxpacmdadd\fR\|(3)] +.IP "\(bu" 4 +XPACmdDel: delete a command +[\fIxpacmddel\fR\|(3)] +.IP "\(bu" 4 +XPAInfoNew: define an info access point +[\fIxpainfonew\fR\|(3)] +.IP "\(bu" 4 +XPAFree: free an access point +[\fIxpafree\fR\|(3)] +.IP "\(bu" 4 +XPAMainLoop: event loop for select server +[\fIxpamainloop\fR\|(3)] +.IP "\(bu" 4 +XPAPoll: poll for \s-1XPA\s0 events +[\fIxpapoll\fR\|(3)] +.IP "\(bu" 4 +XPACleanup: release reserved \s-1XPA\s0 memory +[\fIxpacleanup\fR\|(3)] +.IP "\(bu" 4 +\&\s-1XPA\s0 Server Macros: accessing structure internals +[\fIxpamacros\fR\|(3)] +.IP "\(bu" 4 +\&\s-1XPA\s0 Race Conditions: how to avoid them +[\fIxparace\fR\|(3)] +.IP "\(bu" 4 +\&\s-1XPA\s0 Out of Memory (\s-1OOM\s0) errors +[\fIxpaoom\fR\|(3)] +.RE +.RS 4 +.RE +.IP "\(bu" 4 +\&\s-1XPA\s0 Client Routines +.RS 4 +.IP "\(bu" 4 +XPAOpen: open a persistent client connection +[\fIxpaopen\fR\|(3)] +.IP "\(bu" 4 +XPAClose: close persistent client connection +[\fIxpaclose\fR\|(3)] +.IP "\(bu" 4 +XPAGet: get data +[\fIxpaget\fR\|(3)] +.IP "\(bu" 4 +XPASet: send data or commands +[\fIxpaset\fR\|(3)] +.IP "\(bu" 4 +XPAInfo: send an info alert +[\fIxpainfo\fR\|(3)] +.IP "\(bu" 4 +XPAGetFd: get data and write to an fd +[\fIxpagetfd\fR\|(3)] +.IP "\(bu" 4 +XPASetFd: read data from and fd and send +[\fIxpasetfd\fR\|(3)] +.IP "\(bu" 4 +XPANSLookup: look up an access point +[\fIxpanslookup\fR\|(3)] +.IP "\(bu" 4 +XPAAccess: get access info +[\fIxpaaccess\fR\|(3)] +.IP "\(bu" 4 +The XPA/Xt Interface: Xt interface to \s-1XPA\s0 +[xpaxt(n)] +.IP "\(bu" 4 +The XPA/Tcl Interface: Tcl interface to \s-1XPA\s0 +[xpatcl(n)] +.RE +.RS 4 +.RE +.IP "\(bu" 4 +Tailoring the \s-1XPA\s0 Environment +.RS 4 +.IP "\(bu" 4 +Environment Variables +[xpaenv(n)] +.IP "\(bu" 4 +Access Control +[xpaacl(n)] +.RE +.RS 4 +.RE +.IP "\(bu" 4 +Miscellaneous +.RS 4 +.IP "\(bu" 4 +Where to Find Example/Test Code +.IP "\(bu" 4 +User Changes Between \s-1XPA\s0 1.0 and 2.0 +.IP "\(bu" 4 +\&\s-1API\s0 Changes Between \s-1XPA\s0 1.0 and 2.0 +.IP "\(bu" 4 +What Does \s-1XPA\s0 Stand For, Anyway? +.RE +.RS 4 +.RE diff --git a/xpa/man/mann/xpaacl.n b/xpa/man/mann/xpaacl.n new file mode 100644 index 0000000..d339c5d --- /dev/null +++ b/xpa/man/mann/xpaacl.n @@ -0,0 +1,251 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpaacl n" +.TH xpaacl n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAAcl: Access Control for \s-1XPA\s0 Messaging\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\s-1XPA\s0 supports host-based access control for each \s-1XPA\s0 access point. You +can enable/disable access control using the \s-1XPA_ACL\s0 environment +variable. You can specify access to specific \s-1XPA\s0 access points for +specific machines using the \s-1XPA_DEFACL\s0 and \s-1XPA_ACLFILE\s0 environment +variables. By default, an \s-1XPA\s0 access point is accessible only to +processes running on the same machine (same as X Windows). +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +When \s-1INET\s0 sockets are in use (the default, as specified by the +\&\fI\s-1XPA_METHOD\s0\fR environment variable), \s-1XPA\s0 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 \s-1LOCAL\s0 sockets, access +is restricted (by definition) to the host machine. +.PP +\&\s-1XPA\s0 access control is enabled by default, but can be turned off by +setting the \fI\s-1XPA_ACL\s0\fR environment variable to \fIfalse\fR. +In this case, any process can access any \s-1XPA\s0 server. +.PP +Assuming that access control is turned on, the \s-1ACL\s0 for an individual +\&\s-1XPA\s0 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: +.PP +Firstly, the \fI\s-1XPA_ACLFILE\s0\fR environment variable can defined to +point to a file of access controls for individual access points. The format +of this file is: +.PP +.Vb 1 +\& class:name ip acl +.Ve +.PP +The first argument is a template that specifies the class:name of the +access point covered by this \s-1ACL\s0. See +\&\s-1XPA\s0 Access Points and Templates +for more information about xpa templates. +.PP +The second argument is the \s-1IP\s0 address (in human-readable format) of +the machine which is being given access. This argument can be +\&\fI*\fR to match all \s-1IP\s0 addresses. It also can be \fI\f(CI$host\fI\fR +to match the \s-1IP\s0 address of the current host. +.PP +The third argument is a string combination of \fIs\fR, \fIg\fR, +or \fIi\fR to allow \fIxpaset\fR, \fIxpaget\fR, or +\&\fIxpainfo\fR access respectively. The \s-1ACL\s0 argument can be +\&\fI+\fR to give \fIsgi\fR access or it can be \fI\-\fR to turn +off all access. +.PP +For example, +.PP +.Vb 3 +\& *:xpa1 somehost sg +\& *:xpa1 myhost + +\& * * g +.Ve +.PP +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. +.PP +Secondly, if the \fI\s-1XPA_ACLFILE\s0\fR does not exist, then a single +default value for all access points can be specified using the +\&\fI\s-1XPA_DEFACL\s0\fR environment variable. The default value for this +variable is: +.PP +.Vb 1 +\& #define XPA_DEFACL "*:* $host +" +.Ve +.PP +meaning that all access points are fully accessible to all processes +on the current host. Thus, in the absence of any \s-1ACL\s0 environment variables, +processes on the current host have full access to all access points +created on that host. This parallels the X11 xhost mechanism. +.PP +Access to an individual \s-1XPA\s0 access point can be changed using the \-acl +parameter for that access point. For example: +.PP +.Vb 1 +\& xpaset \-p xpa1 \-acl "somehost \-" +.Ve +.PP +will turn off all access control for somehost to the xpa1 access point, while: +.PP +.Vb 1 +\& xpaset \-p XPA:xpa1 \-acl "beberly gs" +.Ve +.PP +will give beberly xpaget and xpaset access to the access point whose +class is \s-1XPA\s0 and whose name is xpa1. +.PP +Similarly, the current \s-1ACL\s0 for a given access point can be retrieved using: +.PP +.Vb 1 +\& xpaget xpa1 \-acl +.Ve +.PP +Of course, you must have xpaget access to this \s-1XPA\s0 access point to +retrieve its \s-1ACL\s0. +.PP +Note that the \s-1XPA\s0 access points registered in the \fIxpans\fR +program also behave according to the \s-1ACL\s0 rules. That is, you cannot +use xpaget to view the access points registered with xpans unless +you have the proper \s-1ACL\s0. +.PP +Note also when a client request is made to an \s-1XPA\s0 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 +\&\s-1XPA\s0 is changed later on. +.PP +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. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpacode.n b/xpa/man/mann/xpacode.n new file mode 100644 index 0000000..b13c7ae --- /dev/null +++ b/xpa/man/mann/xpacode.n @@ -0,0 +1,181 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpacode n" +.TH xpacode n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPACode: Where to Find Example/Test Code\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +The \s-1XPA\s0 source code directory contains two test programs, +\&\fIstest.c\fR, and \fIctest.c\fR that can serve as +examples for writing \s-1XPA\s0 servers and clients, respectively. +They also can be used to test various features of \s-1XPA\s0. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +To build the \s-1XPA\s0 test programs, execute: +.PP +.Vb 1 +\& make All +.Ve +.PP +in the \s-1XPA\s0 source directory to generate the \fIstest\fR and +\&\fIctest\fR programs. (\s-1NB:\s0 this should work on all platforms, +although we have had problems with unresolved externals on one +Sun/Solaris machine, for reasons still unknown.) +.PP +The stest program can be executed with no arguments to start +an \s-1XPA\s0 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: +.PP +.Vb 4 +\& 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 +.Ve +.PP +etc. You also can use ctest to do the same thing, or to iterate: +.PP +.Vb 4 +\& 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 +.Ve +.PP +More options are available: see the stest.c and ctest.c code itself, which +were used extensively to debug \s-1XPA\s0. +.PP +The file test.tcl in the \s-1XPA\s0 source directory gives examples for using the +XPATclInterface. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpacommon.n b/xpa/man/mann/xpacommon.n new file mode 100644 index 0000000..1a456ed --- /dev/null +++ b/xpa/man/mann/xpacommon.n @@ -0,0 +1,302 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpacommon n" +.TH xpacommon n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPACommon: Getting Common Information About Access Points\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +There are various kinds of generic information you can retrieve about +an \s-1XPA\s0 access point by using the xpaget command. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +You can find out which \s-1XPA\s0 access points have been registered with +the currently running +\&\s-1XPA\s0 name server +by executing the +xpaget +command to retrieve info from the \s-1XPA\s0 name server: +.PP +.Vb 1 +\& xpaget xpans +.Ve +.PP +If, for example, the +stest test server program +is running, the following \s-1XPA\s0 access points will be returned (the specifics +of the returned info will vary for different machines and users): +.PP +.Vb 4 +\& 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 +.Ve +.PP +Note that access to this information is subject to the usual +\&\s-1XPA\s0 Access Control restrictions. +.PP +Each \s-1XPA\s0 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 +\&\fIXPAGet()\fR +or +\&\fIXPASet()\fR +in programs, e.g: +.PP +.Vb 3 +\& xpaget ds9 \-acl +\& xpaget ds9 \-help +\& xpaget ds9 env FOO +\& +\& xpaset \-p ds9 env FOO foofoo +.Ve +.PP +With the exception of \fB\-help\fR and \fB\-version\fR, reserved +sub-commands are available only on the machine on which the \s-1XPA\s0 server +itself is running. +.PP +The following reserved sub-commands are defined for all access points: +.IP "\(bu" 4 +\&\fB\-acl\fR get (set) the access control list [options: host type acl, for set] +.Sp +The 'xpaset' option allows you to add a new acl for a given host, or change +the acl for an existing host. See +\&\s-1XPA\s0 Access Control +for more information. +This access point is available only on the server machine. +.IP "\(bu" 4 +\&\fB\-env\fR get (set) an environment variable [options: name (value, for set)] +.Sp +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.) +.IP "\(bu" 4 +\&\fB\-clipboard\fR set(get) information on a named clipboard +.Sp +Clients can store \s-1ASCII\s0 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: +.Sp +.Vb 2 +\& [data] | xpaset [server] \-clipboard add|append [clipboard_name] +\& xpaset \-p [server] \-clipboard delete [clipboard_name] +.Ve +.Sp +Use \*(L"add\*(R" to create a new clipboard or replace the contents of an existing +one. Use \*(L"append\*(R" to append to an existing clipboard. +.Sp +Information on a named clipboard is retrieved using: +.Sp +.Vb 1 +\& xpaget [server] \-clipboard [clipboard_name] +.Ve +.IP "\(bu" 4 +\&\fB\-exec\fR set: execute commands from buffer [options: none] +.Sp +If \-exec is specified in the paramlist of an 'xpaset' call, then further +sub-commands will be retrieved from the data buffer. +.IP "\(bu" 4 +\&\fB\-help\fR get: return help string for this \s-1XPA\s0 or sub-command [options: name (for sub\-commands)] +.Sp +Each \s-1XPA\s0 access point and each \s-1XPA\s0 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 \s-1XPA\s0 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. +.IP "\(bu" 4 +\&\fB\-ltimeout\fR get (set) the long timeout value [options: seconds|reset] +.Sp +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 \*(L"reset\*(R" is +specified, then the timeout value will be reset to the default value. +.IP "\(bu" 4 +\&\fB\-nsconnect\fR set: re-establish name server connection to all \s-1XPA\s0's [options: none] +.Sp +If the +\&\s-1XPA\s0 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 \s-1XPA\s0 name (since the latter requires the xpans +connection!): +.Sp +.Vb 1 +\& xpaset \-p 838e2f67:1268 \-nsconnect +.Ve +.Sp +See xpans for more information. +.IP "\(bu" 4 +\&\fB\-nsdisconnect\fR set: break name server connection to all \s-1XPA\s0's [options: none] +.Sp +This sub-command will terminate the connection to the +\&\s-1XPA\s0 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. +.IP "\(bu" 4 +\&\fB\-stimeout\fR get (set) the short timeout value [options: seconds|reset] +.Sp +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 \*(L"reset\*(R" is +specified, then the timeout value will be reset to the default value. +.IP "\(bu" 4 +\&\fB\-remote\fR set: register xpa with remote server [options: host[:port] [acl]] [\-proxy] +.Sp +This sub-command will register the \s-1XPA\s0 access point with the \s-1XPA\s0 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 \*(L"+\*(R" (meaning the remote +host can xpaset, xpaget, xpainfo or xpaaccess). If the acl is +specified as \*(L"\-\*(R", then the access point is unregistered. +See Communication Between Machines +for more information on how this sub-command is used. +.IP "\(bu" 4 +\&\fB\-version\fR get: return \s-1XPA\s0 version string [options: none] +.Sp +The version refers to the version of \s-1XPA\s0 used to define this access point +(currently something like 2.0). +.PP +You can add your own reserved commands to all \s-1XPA\s0 access points by using the +\&\fIXPACmdAdd()\fR +routine, passing the \s-1XPA\s0 handle returned by \fI\s-1XPA\s0 XPAGetReserved(void)\fR +as the first argument. Note again that these will only be available on the +machine where the \s-1XPA\s0 service is running. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpaconvert.n b/xpa/man/mann/xpaconvert.n new file mode 100644 index 0000000..035ef0b --- /dev/null +++ b/xpa/man/mann/xpaconvert.n @@ -0,0 +1,267 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpaconvert n" +.TH xpaconvert n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAConvert: Converting the \s-1XPA\s0 \s-1API\s0 to 2.0\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +This document describes tips for converting from xpa 1.0 (Xt-based +xpa) to xpa 2.0 (socket-based xpa). +.SH "DESCRIPTION" +.IX Header "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). +.IP "\(bu" 4 +The existence of the cpp \s-1XPA_VERSION\s0 directive to distinguish between 1.0 +(where it is not defined) and 2.0 (where it is defined). +.IP "\(bu" 4 +Remove the first widget argument from all send and receive server +callbacks. Also change first 2 arguments from XtPointer to void +*. For example: +.Sp +#ifdef \s-1XPA_VERSION\s0 +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 +.IP "\(bu" 4 +Server callbacks should be declared as returning int instead +of void. They now should return 0 for no errors, \-1 for error. +.IP "\(bu" 4 +The mode flags have changed when defining \s-1XPA\s0 server callbacks. +The old \fIS\fR flag (save buffer) is replaced by \fIfreebuf=false\fR. +The old \fIE\fR flag (empty buffer is \s-1OK\s0) is no longer used (it +was an artifact of the X implementation). +.IP "\(bu" 4 +Change \fINewXPACommand()\fR to \fIXPAcmdNew()\fR, with the new calling sequence: +.Sp +.Vb 1 +\& xpa = NewXPACommand(toplevel, NULL, prefix, NULL); +.Ve +.Sp +is changed to: +.Sp +.Vb 1 +\& xpa = XPACmdNew(xclass, name); +.Ve +.IP "\(bu" 4 +Change the \fIAddXPACommand()\fR subroutine name to XPACmdAdd (with the same +calling sequence): +.Sp +.Vb 3 +\& AddXPACommand(xpa, "file", +\& "\etdisplay a new file\en\et\et requires: filename", +\& NULL, NULL, NULL, XPAReceiveFile, text, NULL); +.Ve +.Sp +is changed to: +.Sp +.Vb 3 +\& XPACmdAdd(xpa, "file", +\& "\etdisplay a new file\en\et\et requires: filename", +\& NULL, NULL, NULL, XPAReceiveFile, text, NULL); +.Ve +.IP "\(bu" 4 +The \fIXPAXtAppInput()\fR routine should be called just before \fIXtAppMainLoop()\fR +to add xpa fds to the Xt event loop: +.Sp +.Vb 2 +\& /* add the xpas to the Xt loop */ +\& XPAXtAddInput(app, NULL); +\& +\& /* process events */ +\& XtAppMainLoop(app); +.Ve +.IP "\(bu" 4 +Change \fINewXPA()\fR to \fIXPANew()\fR and call \fIXPAXtAddInput()\fR if the XtAppMainLoop +routine already has been entered: +.Sp +.Vb 4 +\& xpa = NewXPA(saotng\->xim\->toplevel, prefix, xparoot, +\& "FITS data or image filename\en\et\et options: file type", +\& XPASendData, new, NULL, +\& XPAReceiveData, new, "SE"); +.Ve +.Sp +is changed to: +.Sp +.Vb 6 +\& sprintf(tbuf, "%s.%s", prefix, xparoot); +\& xpa = XPANew("SAOTNG", tbuf, +\& "FITS data or image filename\en\et\et options: file type", +\& XPASendData, new, NULL, +\& XPAReceiveData, new, "SE"); +\& XPAXtAddInput(XtWidgetToApplicationContext(saotng\->xim\->toplevel), xpa); +.Ve +.IP "\(bu" 4 +Change \fIXPAInternalReceiveCommand()\fR to \fIXPACmdInternalReceive()\fR +remove first argument in the calling sequence): +.Sp +.Vb 3 +\& XPAInternalReceiveCommand(im\->saotng\->xim\->toplevel, +\& im\->saotng, im\->saotng\->commands, +\& "zoom reset", NULL, 0); +.Ve +.Sp +is changed to: +.Sp +.Vb 2 +\& XPACmdInternalReceive(im\->saotng, im\->saotng\->commands, +\& "zoom reset", NULL, 0); +.Ve +.IP "\(bu" 4 +Change DestroyXPA to XPAFree: +.Sp +.Vb 1 +\& DestroyXPA(im\->dataxpa); +.Ve +.Sp +is changed to: +.Sp +.Vb 1 +\& XPAFree(im\->dataxpa); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpaenv.n b/xpa/man/mann/xpaenv.n new file mode 100644 index 0000000..ead081c --- /dev/null +++ b/xpa/man/mann/xpaenv.n @@ -0,0 +1,482 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpaenv n" +.TH xpaenv n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAEnv: Environment Variables for \s-1XPA\s0 Messaging\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +Describes the environment variables which can be used to tailor the overall +\&\s-1XPA\s0 environment. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The following environment variables are supported by \s-1XPA:\s0 +.IP "\(bu" 4 +\&\fB\s-1XPA_ACL\s0\fR +.Sp +If \fI\s-1XPA_ACL\s0\fR is \fItrue\fR, then +host-based \s-1XPA\s0 Access Control +is turned on and only specified machines can access specified access +points. If \fIfalse\fR, then access control is turned off and any +machine can access point. The default is turn turn access control on. +.IP "\(bu" 4 +\&\fB\s-1XPA_ACLFILE\s0\fR +.Sp +If +\&\s-1XPA\s0 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: \fI\f(CI$HOME\fI/acls.xpa\fR. +.IP "\(bu" 4 +\&\fB\s-1XPA_CONNECT_TIMEOUT\s0\fR +.Sp +When an \s-1XPA\s0 server first starts up, it immediately tries to +connect to the \s-1XPA\s0 name server program (xpans) on the host specified by +the \fI\s-1XPA_NSINET\s0\fR 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 \fIconnect()\fR system call times out. Therefore, an alarm is started +to interrupt the \fIconnect()\fR 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 \fIconnect()\fR to time out, set the value of this variable to +0. Normally, users would not change this variable at all. +.IP "\(bu" 4 +\&\fB\s-1XPA_CLIENT_DOXPA\s0\fR +.Sp +Normally, an \s-1XPA\s0 client (xpaget, xpaset, etc.) will process incoming +\&\s-1XPA\s0 server requests while awaiting the completion of the client request. +Setting this variable to \*(L"false\*(R" will prevent \s-1XPA\s0 server requests from +being processed by the client. +.IP "\(bu" 4 +\&\fB\s-1XPA_DEFACL\s0\fR +.Sp +If +\&\s-1XPA\s0 Access Control +is turned on, this variable specifies the default access control +condition for all access points, if the \fI\s-1XPA_ACLFILE\s0\fR file does +not exist. The default acl is: \fI\f(CI$host:\fI* \f(CI$host\fI +\fR, meaning that +all processes on the host machine have full access to all access points. +.IP "\(bu" 4 +\&\fB\s-1XPA_HOST\s0\fR +.Sp +For the \s-1INET\s0 socket method, \s-1XPA\s0 utilizes the canonical hostname (as +returned by the \fIgethostname()\fR routine) to construct the \s-1IP\s0 part of the +method id. Under some circumstances, this might not be a correct choice +of name and \s-1IP\s0. For example, if an \s-1XPA\s0 server is started on a machine +running \s-1VPN\s0, you might want to use the \s-1VPN\s0 name and \s-1IP\s0 instead of the +canonical host name, so that other machines in the \s-1VPN\s0 network can +access the server. In this case, you can set the \s-1XPA_HOST\s0 to be +the \s-1VPN\s0 name (if resolvable) or, more easily, the \s-1VPN\s0 \s-1IP\s0. +.IP "\(bu" 4 +\&\fB\s-1XPA_IOCALLSXPA\s0\fR +.Sp +Setting this variable causes all \s-1XPA\s0 socket \s-1IO\s0 calls to process +outstanding \s-1XPA\s0 requests whenever the primary socket is not ready for +\&\s-1IO\s0. This means that a server making a client call will (recursively) +process incoming server requests while waiting for client completion. +This inter-IO \s-1XPA\s0 processing avoids a rare +\&\s-1XPA\s0 Race Condition: two or more +\&\s-1XPA\s0 servers sending messages to one another using an \s-1XPA\s0 client +routine such as \fIXPASet()\fR can deadlock while each waits for the other +server to respond. This can happen, for example, if the servers call +\&\fIXPAPoll()\fR with a time limit, and send messages in between the polling call. +.Sp +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 \s-1XPA\s0 requests within socket \s-1IO\s0 +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. +.IP "\(bu" 4 +\&\fB\s-1XPA_LOGNAME\s0\fR +.Sp +\&\s-1XPA\s0 preferentially uses the de facto standard environment variable +\&\s-1LOGNAME\s0 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 \s-1XPA_LOGNAME\s0 +variable to set the user name. (If neither exists, then getpwuid(\fIgeteuid()\fR) +is used as a last resort). +.IP "\(bu" 4 +\&\fB\s-1XPA_LONG_TIMEOUT\s0\fR +.Sp +\&\s-1XPA\s0 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 \fIshort\fR timeout for protocol communication +and a \fIlong\fR for data communication. +.Sp +The \fI\s-1XPA_LONG_TIMEOUT\s0\fR variable controls the \fIlong\fR +timeout and is used to prevent hangs in cases where communication +between the client and server that is \fInot\fR controlled by the +\&\s-1XPA\s0 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 \fIlong\fR timeout is set to 180 seconds. +Setting the value to \-1 will disable \fIlong\fR timeouts and allow +an infinite amount of time. +.IP "\(bu" 4 +\&\fB\s-1XPA_MAXHOSTS\s0\fR +.Sp +The maximum number of access points that the programs +\&\fIxpaset\fR, \fIxpaget\fR, and \fIxpainfo\fR will +communicate with at one time. The default is 64, meaning, for +example, that the \fIxpaset\fR program will not send a message +to more than 100 access points at one time and \fIxpaget\fR will +not retrieve from more than 100 access points at one time. +.IP "\(bu" 4 +\&\fB\s-1XPA_METHOD\s0\fR +.Sp +Determines the socket connection method used by this session of \s-1XPA\s0. +The choices are: \fIinet\fR (to use \s-1INET\s0 or Internet-based +sockets), \fIlocalhost\fR (to use the machines localhost inet +socket), or \fIlocal (unix)\fR (to use \s-1UNIX\s0 sockets). The default +is \fI\s-1INET\s0\fR. Using the \fIinet\fR method will allow access +from other machines (subject to access controls) but using +\&\fIlocalhost\fR or \fIlocal\fR 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). +.Sp +Once defined, the first registration of an \s-1XPA\s0 access point will +ensure that an instance of the +\&\s-1XPA\s0 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. +.IP "\(bu" 4 +\&\fB\s-1XPA_NSINET\s0\fR +.Sp +For the \fIinet\fR method of socket connection, this variable +specifies the host and port on which the +\&\s-1XPA\s0 Name Server (xpans) +is listens for new access points. The default is \fI\f(CI$host:\fI$port\fR, +meaning that the default \s-1XPA\s0 port (14285) on the current machine +(as returned by \fIgethostname()\fR) is used. If several machines were all +accessing the same \s-1XPA\s0 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 \fImyhost:$port\fR would +mean that the xpans name server is running on myhost and uses the +default port 12345. All machines would then get the \s-1XPA\s0 access points +registered with that name server, subject to access controls. +.Sp +The port used by xpans to register its \s-1XPA\s0 access point normally is +taken to be one greater than the port on which it receives new access +points from \s-1XPA\s0 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, \f(CW$host:12345\fR,23456 will listen +for new access ports on 12345 and will accept \s-1XPA\s0 commands on 23456. +.IP "\(bu" 4 +\&\fB\s-1XPA_NSREGISTER\s0\fR +.Sp +This boolean variable specifies whether a server registers its \s-1XPA\s0 +access point with the specified xpans name server. The default is +\&\fItrue\fR. If set to \fIfalse\fR, 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 \s-1DNS\s0 hang) but you still wish to and can use the server with a +remote xpans (e.g., ds9's Virtual Observatory capability). +.IP "\(bu" 4 +\&\fB\s-1XPA_NSUNIX\s0\fR +.Sp +For the \fIlocal\fR method of socket connection, this variable +specifies the name of the Unix file that will be used to access the +\&\s-1XPA\s0 Name Server (xpans). The default is +\&\fIxpans_unix\fR. This variable is not usually needed. Note that +is the \fIlocal\fR socket method is used, then remote machines will +not be able to access the xpans name server or the registered \s-1XPA\s0 access +points. +.IP "\(bu" 4 +\&\fB\s-1XPA_NSUSERS\s0\fR +.Sp +This variable specifies whether other users' access points will be +returned by the +\&\s-1XPA\s0 Name Server (xpans) for use by +\&\fIxpaget\fR, \fIxpaset\fR, 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: +.Sp +.Vb 1 +\& xpaget ds9 colormap +.Ve +.Sp +you might get information from your own ds9 as well as +from another user running ds9 on the same machine. The +\&\fI\s-1XPA_NSUSERS\s0\fR 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 +\&\fI\s-1XPA_NSUSERS\s0\fR variable to \fIeric,fred\fR, then you would be +able to communicate with both eric and fred's access points. Note that +this variable can be overridden using the \fI\-u\fR switch on the +\&\fIxpaget\fR, \fIxpaset\fR, and \fIxpainfo\fR programs. +.IP "\(bu" 4 +\&\fB\s-1XPA_PORT\s0\fR +.Sp +A semi-colon delimited list of user specified ports to use for specific +\&\s-1XPA\s0 access points. The format is each specification is: +.Sp +class:template port1[ port2] +.Sp +where \fBport1\fR is the main (command) port for the access point and +\&\fBport2\fR is the (secondary) data port. If port2 is not specified, +it defaults to a value of 0 (meaning the system assigns the port). +.Sp +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 \s-1XPA\s0 program should be started up with the +outside machine in its \s-1ACL\s0 list. Then, when the inside program is +started with specified ports, outside \s-1XPA\s0 programs can use +\&\*(L"machine:port\*(R" 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 \s-1XPA\s0 name server: +.Sp +export XPA_PORT=\*(L"DS9:ds9 12345 12346\*(R" # on machine \*(L"inside\*(R" +cat foo.fits | xpaset inside:12345 fits # on machine \*(L"outside\*(R" +.Sp +Note that 2 ports are required for full \s-1XPA\s0 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. +.Sp +This support is somewhat experimental. If you run into problems, please +let us know. +.IP "\(bu" 4 +\&\fB\s-1XPA_PORTFILE\s0\fR +.Sp +A list of user-specified port to use for specific xpa access points. +The format of the file is: +.Sp +class:template port1 [port2] +.Sp +where \fBport1\fR is the main port for the access point and +\&\fBport2\fR is the data port. If port2 is not specified, it defaults +to a value of 0 (meaning the system assigns the port). See +\&\fB\s-1XPA_PORT\s0\fR above for an explanation of user-specified ports. +.IP "\(bu" 4 +\&\fB\s-1XPA_SHORT_TIMEOUT\s0\fR +.Sp +\&\s-1XPA\s0 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 \fIshort\fR timeout for protocol communication +and a \fIlong\fR for data communication. +.Sp +The \fI\s-1XPA_SHORT_TIMEOUT\s0\fR variable +controls the \fIshort\fR timeout and is used to prevent hangs +in cases where the \s-1XPA\s0 protocol requires internal communication between +the client and server that is controlled by the \s-1XPA\s0 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 \fIshort\fR is 30 seconds (which is +a pretty long time, actually). Setting the value to \-1 will disable +\&\fIshort\fR timeouts and allow an infinite amount of time. +.IP "\(bu" 4 +\&\fB\s-1XPA_SIGUSR1\s0\fR +.Sp +If the value of this variable is \fItrue\fR, then \s-1XPA\s0 will +catch \s-1SIGUSR1\s0 signals when performing an I/O operation in order to +curtail that operation. This facility allows users to send a \s-1SIGUSR1\s0 +signal to an \s-1XPA\s0 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 \s-1SIGUSR1\s0 signal is ignored at all other +times, so that its safe to send the signal at any time. If the +variable is set to \fIfalse\fR, then \s-1SIGUSR1\s0 is not used at +all. Turning off \s-1SIGUSR1\s0 would be desired in cases there the program +uses \s-1SIGUSR1\s0 for some other reason and does not want \s-1XPA\s0 interfering. +The default is to use the signal. +.IP "\(bu" 4 +\&\fB\s-1XPA_TIMESTAMP_ERRORS\s0\fR +.Sp +If \fI\s-1XPA_TIMESTAMP_ERRORS\s0\fR is \fItrue\fR, then error +messages will include a date/time string. This can be useful when +\&\s-1XPA\s0 errors are being saved in an error log (e.g. Web/CGI use). The +default is false. +.IP "\(bu" 4 +\&\fB\s-1XPA_TMPDIR\s0\fR +.Sp +This variable specifies the directory into which \s-1XPA\s0 logs, Unix +socket files (when \fI\s-1XPA_METHOD\s0\fR is \fIlocal\fR), etc. are +stored. The default is \fI/tmp/.xpa\fR. +.IP "\(bu" 4 +\&\fB\s-1XPA_VERBOSITY\s0\fR +.Sp +Specify the verbosity level of error messages. If the value is +set to \fI0\fR, \fIfalse\fR, or \fIoff\fR, then no error +messages are printed to stderr. If the value is \fI1\fR, then +important \s-1XPA\s0 error messages will be output. If the value is +set to \fI2\fR, \s-1XPA\s0 warnings about out-of-sync messages will also +be output. These latter almost always can be ignored. +.IP "\(bu" 4 +\&\fB\s-1XPA_VERSIONCHECK\s0\fR +.Sp +Specify whether a new access point should check its major and minor \s-1XPA\s0 +version number against the version used by the xpans name server at +registration time. The default is \fItrue\fR. 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 \s-1XPA\s0 server and by the xpans process and warnings will be +issued by each. Also, instead of the values of \fItrue\fR or +\&\fIfalse\fR, 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). +.Sp +In general, it is a bad idea to run an XPA-enabled server program +using a version of \s-1XPA\s0 newer than the basic xpaset, xpaget, xpaaccess, +xpans programs. This sort of mismatch usually will not work due to +protocol changes. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages +.SH "POD ERRORS" +.IX Header "POD ERRORS" +Hey! \fBThe above document had some coding errors, which are explained below:\fR +.IP "Around line 458:" 4 +.IX Item "Around line 458:" +\&'=item' outside of any '=over' +.IP "Around line 509:" 4 +.IX Item "Around line 509:" +You forgot a '=back' before '=head1' diff --git a/xpa/man/mann/xpainet.n b/xpa/man/mann/xpainet.n new file mode 100644 index 0000000..4847654 --- /dev/null +++ b/xpa/man/mann/xpainet.n @@ -0,0 +1,396 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpainet n" +.TH xpainet n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAInet: \s-1XPA\s0 Communication Between Hosts\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\s-1XPA\s0 uses standard inet sockets to support communication between two or +more host computers. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +When the Communication Method is set to +\&\fBinet\fR (as it is by default), \s-1XPA\s0 can be used to communicate +between different computers on the Internet. \s-1INET\s0 sockets utilize the +\&\s-1IP\s0 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. +.PP +\&\s-1XPA\s0 supports a host-based Access Control mechanism +to prevent unauthorized access of \s-1XPA\s0 access points by other computers +on the Net. By default, only the machine on which the \s-1XPA\s0 server is +running can access \s-1XPA\s0 services. Therefore, setting up communication +between a local \s-1XPA\s0 server machine and a remote client machine +requires a two-part registration process: +.IP "\(bu" 4 +the \s-1XPA\s0 service on the local machine must be made known to the +remote machine +.IP "\(bu" 4 +the remote machine must be given permission to access the local +\&\s-1XPA\s0 service +.PP +Three methods by which this remote registration can be accomplished +are described below. +.PP +\&\fBManual Registration\fR +.PP +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 \s-1XPA\s0 access points +using xpaset and the \fB\-acl\fR sub-command. For example, +consider the \s-1XPA\s0 test program \*(L"stest\*(R" running on a local machine. By +default the access control for the access point named \*(L"xpa\*(R" is +restricted to that machine: +.PP +.Vb 3 +\& [sh]$ xpaget xpa \-acl +\& *:* 123.456.78.910 gisa +\& *:* localhost gisa +.Ve +.PP +Using xpaset and the \fB\-acl\fR 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: +.PP +.Vb 1 +\& [sh]$ xpaset \-p xpa \-acl "remote_machine g" +.Ve +.PP +This results in the following access permissions on the local machine: +.PP +.Vb 4 +\& [sh]$ xpaget xpa \-acl +\& XPA:xpa 234.567.89.012 g +\& *:* 123.456.78.910 gisa +\& *:* localhost gisa +.Ve +.PP +The remote client can now use the local server's xpans name server to +establish communication with the local \s-1XPA\s0 service. This can be done +on a call-by-call basis using the \fB\-i\fR switch on xpaset, xpaget, etc: +.PP +.Vb 6 +\& [sh]$ xpaget \-i "local_machine:12345" xpa +\& class: XPA +\& name: xpa +\& method: 88877766:2778 +\& sendian: little +\& cendian: big +.Ve +.PP +Alternatively, the \s-1XPA_NSINET\s0 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 \s-1XPA\s0 program is run: +.PP +.Vb 7 +\& [csh]$ setenv XPA_NSINET \*(Aqkarapet:$port\*(Aq +\& [csh]$ xpaget xpa +\& class: XPA +\& name: xpa +\& method: 88877766:2778 +\& sendian: little +\& cendian: big +.Ve +.PP +Here, '$port' means to use the default \s-1XPA\s0 name service port (14285). +not a port environment variable. +.PP +Access permission for remote client machines can be stored in a file +on the local machine pointed to by the \fB\s-1XPA_ACLFILE\s0\fR environment +variable or using the \fB\s-1XPA_DEFACL\s0\fR environment variable. See <A +HREF=\*(L"./acl.html\*(R">\s-1XPA\s0 Access Control for more information. +.PP +\&\fBRemote Registration\fR +.PP +If xpans is running on the remote client machine, then a local xpaset +command can be used with the \fB\-remote\fR sub-command to +register the local \s-1XPA\s0 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 \*(L"stest\*(R" 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 \fB\-remote\fR sub-command: +.PP +.Vb 1 +\& [sh]$ ./xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq + +.Ve +.PP +To register the local xpa access point on the remote machine with xpaget +access only, execute: +.PP +.Vb 1 +\& [sh]$ ./xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq g +.Ve +.PP +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: +.PP +.Vb 2 +\& [csh]$ xpaget xpans +\& XPA xpa gs 88877766:2839 eric +.Ve +.PP +The xpa access point can now be utilized on the remote machine without +further setup: +.PP +.Vb 6 +\& [csh]$ xpaget xpa +\& class: XPA +\& name: xpa +\& method: 838e2f68:2839 +\& sendian: little +\& cendian: big +.Ve +.PP +To unregister remote access from the local machine, use the same +command but with a '\-' argument: +.PP +.Vb 1 +\& [sh]$ xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq \- +.Ve +.PP +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 \s-1XPA\s0 command can be used to send or +receive messages to the remote and local services. +.PP +\&\fB\s-1XPANS\s0 Proxy Registration\fR +.PP +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 \s-1LAN\s0. The situation is more complicated when the +\&\s-1XPA\s0 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 \s-1XPA\s0 server inside a firewall. +.PP +To allow locally fire-walled \s-1XPA\s0 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 +\&\fB\-remote\fR sub-command is again used, but with an additional +\&\fB\-proxy\fR argument added to the end of the command: +.PP +.Vb 1 +\& [sh]$ ./xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq g \-proxy +.Ve +.PP +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: +.PP +.Vb 2 +\& [csh]$ xpaget xpans +\& XPA xpa gs @88877766:2839 eric +.Ve +.PP +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 \s-1XPA\s0 +access point is contacted using \s-1XPA\s0 programs (xpaset, xpaget, etc.) or +libraries: +.PP +.Vb 6 +\& [csh]$ xpaget xpa +\& class: XPA +\& name: xpa +\& method: 88877766:3053 +\& sendian: little +\& cendian: big +.Ve +.PP +Of course, the underlying processing of the \s-1XPA\s0 requests is very much +different when xpans proxy is involved. Instead of an \s-1XPA\s0 program such +contacting the \s-1XPA\s0 service directly, it contacts the local xpans. +Acting as a proxy server, xpans communicates with the \s-1XPA\s0 service +using the command channel established at registration time. Commands +(including establishing a new data channel) are sent between xpans and +the \s-1XPA\s0 service to set up a new message transfer, and then data is fed +to/from the xpa request, through xpans, from/to the \s-1XPA\s0 service. In +this way, it can be arranged so that connections between the +fire-walled \s-1XPA\s0 service and the remote client are always initiated by +the \s-1XPA\s0 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. +.PP +The xpans proxy scheme requires that the remote client allow the local +\&\s-1XPA\s0 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 \fB\s-1XPA_NSINET\s0\fR +environment variable. This variable takes the form: +.PP +.Vb 1 +\& setenv XPA_NSINET machine:port1[,port2[,port3]] +.Ve +.PP +where port1 is the main connecting port, port2 is the \s-1XPA\s0 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. +.PP +For example, to change the port assignments so that xpans listens +for registration commands on port 12345 and data commands on port 28573: +.PP +.Vb 1 +\& setenv XPA_NSINET myhost:12345 +.Ve +.PP +Alternatively, all three ports can be assigned explicitly: +.PP +.Vb 1 +\& setenv XPA_NSINET remote:12345,3000,12346 +.Ve +.PP +In this case 12345 and 12346 should be open for incoming connections. +The \s-1XPA\s0 access port (which need not be open to the outside +world) is set to 3000. +.PP +Finally, note that we currently have no mechanism to cope with +Internet proxy servers (such as \s-1SOCKS\s0 servers). If an \s-1XPA\s0 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 \s-1XPA\s0 service with a remote machine. We hope to implement +support for \s-1SOCKS\s0 proxy in a future release. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpaintro.n b/xpa/man/mann/xpaintro.n new file mode 100644 index 0000000..2978e6b --- /dev/null +++ b/xpa/man/mann/xpaintro.n @@ -0,0 +1,250 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpaintro n" +.TH xpaintro n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAIntro: Introduction to the \s-1XPA\s0 Messaging System\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +A brief introduction to the \s-1XPA\s0 messaging system, which provides +seamless communication between all kinds of Unix event-driven +programs, including X programs, Tcl/Tk programs, and Perl programs. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1XPA\s0 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 \s-1XPA\s0 client commands in +the shell or by utilizing such commands in scripts. Because \s-1XPA\s0 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 \s-1XPA\s0 services, and client access can be extended or modified +easily at any time. +.PP +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 \s-1TCP\s0 sockets as +a transport mechanism, \s-1XPA\s0 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 \s-1XPA\s0 servers +across a network. +.PP +\&\s-1XPA\s0 implements a layered interface that is designed to be useful both +to software developers and to users. The interface consists of a +library of \s-1XPA\s0 client and server routines for use in programs and a +suite of high-level user programs built on top of these libraries. +Using the \s-1XPA\s0 library, access points can be added to +Tcl/Tk +programs, +Xt +programs, or to Unix programs that use the \s-1XPA\s0 event loop or any +event loop based on \fIselect()\fR. 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. +.PP +The major components of the \s-1XPA\s0 layered interface are: +.IP "\(bu" 4 +A set of \s-1XPA\s0 server routines, centered on +\&\fIXPANew()\fR, +which are used by \s-1XPA\s0 server programs to tag public access points with +string identifiers and to register send and receive callbacks for +these access points. +.IP "\(bu" 4 +A set of \s-1XPA\s0 client routines, centered on the +\&\fIXPASet()\fR +and +\&\fIXPAGet()\fR, +which are used by external client applications to exchange data and +commands with an \s-1XPA\s0 server. +.IP "\(bu" 4 +High-level programs, centered on +xpaset +and +xpaget, +which allow data +and information to be exchanged with \s-1XPA\s0 server programs from the +command line and from scripts. These programs have the command syntax: +.Sp +.Vb 2 +\& [data] | xpaset [qualifiers ...] +\& xpaget [qualifiers ...] +.Ve +.IP "\(bu" 4 +An \s-1XPA\s0 name server program, +xpans, +through which \s-1XPA\s0 access point names are +registered by servers and distributed to clients. +.PP +Defining an \s-1XPA\s0 access point is easy: a server application calls +\&\fIXPANew()\fR, +\&\fIXPACmdNew()\fR, +or the experimental +\&\fIXPAInfoNew()\fR +routine to +create a named public access point. An \s-1XPA\s0 service can specify \*(L"send\*(R" +and \*(L"receive\*(R" callback procedures (or an \*(L"info\*(R" procedure in the case +of \fIXPAInfoNew()\fR) 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 \s-1XPA\s0 server program enters +its usual event loop (or uses the standard \s-1XPA\s0 event loop). +.PP +Clients communicate with these \s-1XPA\s0 public access points +using programs such as +xpaget, +xpaset, and +xpainfo +(at the command line), +or routines such as +\&\fIXPAGet()\fR, +\&\fIXPASet()\fR, +and +\&\fIXPAInfo()\fR +within a program. Both methods require specification of the name of +the access point. The xpaget program returns data or other +information from an \s-1XPA\s0 server to its standard output, while the +xpaset program sends data or commands from its standard input to an +\&\s-1XPA\s0 application. The corresponding \s-1API\s0 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., \*(L"ds9*\*(R"), then +communication will take place with all servers matching that template. +.PP +Please note that \s-1XPA\s0 currently is not thread-safe. All \s-1XPA\s0 calls must be +in the same thread. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpamethod.n b/xpa/man/mann/xpamethod.n new file mode 100644 index 0000000..faecd86 --- /dev/null +++ b/xpa/man/mann/xpamethod.n @@ -0,0 +1,200 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpamethod n" +.TH xpamethod n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAMethod: \s-1XPA\s0 Communication Methods\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\s-1XPA\s0 supports both inet and unix (local) socket communication. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1XPA\s0 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 \s-1XPA\s0 processes in a +session and the global environment variable \s-1XPA_METHOD\s0 should be used +to set up the desired method. By default, the preferred method is +\&\*(L"inet\*(R", which is appropriate for most users. You can set up a +different method by typing something like: +.PP +.Vb 3 +\& setenv XPA_METHOD local # unix csh +\& XPA_METHOD=local; export XPA_METHOD # unix sh, bash, windows/cygwin +\& set XPA_METHOD=localhost # dos/windows +.Ve +.PP +The options for \s-1XPA_METHOD\s0 are: \fBinet\fR, \fBunix\fR (or +\&\fBlocal\fR), and \fBlocalhost\fR. 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 \s-1AUTOEXEC\s0.BAT file (I think!). +.PP +By default, \fBinet\fR sockets are used by \s-1XPA\s0. These are the standard +Internet sockets that are used by programs such as Netscape, +ftp. etc. Inet sockets utilize the \s-1IP\s0 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 +\&\s-1XPA\s0 has an Access Control mechanism to +prevent unauthorized access of \s-1XPA\s0 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 \s-1XPA\s0 communication between machines, see +Communication Between Machines. +.PP +In you are using \s-1XPA\s0 on a machine without an Internet connection, then +inet sockets are not appropriate. In fact, an \s-1XPA\s0 process often will +hang for many seconds while waiting for a response from the Domain +Name Service (\s-1DNS\s0) when using inet sockets. Instead of inet sockets, +users on Unix platforms can also use \fBunix\fR sockets (also known +as local sockets). These sockets are based on the local file system +and do not make use of the \s-1DNS\s0. 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. +.PP +Users not connected to the Internet also can use \fBlocalhost\fR +sockets. These are also inet-type sockets but the \s-1IP\s0 address used for +the local machine is the \fBlocalhost\fR address, 0x7F000001, instead +of the real \s-1IP\s0 of the machine. Depending on how sockets are set up for +a given platform, communication with the \s-1DNS\s0 usually is not required in +this case (though of course, \s-1XPA\s0 cannot interact with other machines). +The localhost method will generally work on both Unix and Windows +platforms, but whether the \s-1DNS\s0 is required or not is subject to +individual configurations. +.PP +A final warning/reminder: if your XPA-enabled server hangs at startup +time and your \s-1XPA_METHOD\s0 is \fBinet\fR, the problem probably is +related to an incorrect Internet configuration. This can be confirmed +by using the \fBunix\fR method or (usually) the \fBlocalhost\fR +method. You can use these alternate methods if other hosts do not need +access to the \s-1XPA\s0 server. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpaname.n b/xpa/man/mann/xpaname.n new file mode 100644 index 0000000..cdb6839 --- /dev/null +++ b/xpa/man/mann/xpaname.n @@ -0,0 +1,158 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpaname n" +.TH xpaname n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAName: What does \s-1XPA\s0 stand for?\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +What does \s-1XPA\s0 stand for? Who knows anymore! +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +What does \s-1XPA\s0 stand for? Dunno! The \s-1XPA\s0 messaging system originally +was built on top of the X Window System and \s-1XPA\s0 was the mnemonic for +\&\fIX Public Access\fR, to emphasize that we were providing public +access to previously private data and algorithms in Xt programs. Now +that \s-1XPA\s0 no longer is tied to X, it can be argued that we ought to +change the name (how about \s-1SPAM:\s0 simple public access mechanism +), but \s-1XPA\s0 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 \s-1XPA\s0 now means, please let us know. +.PP +If you think this is bad, consider the \s-1MMT\s0 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 +\&\fIMultiple Mirror Telescope\fR. 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 \s-1MMT\s0 stands for ... \s-1MMT\s0! +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpaoom.n b/xpa/man/mann/xpaoom.n new file mode 100644 index 0000000..9dfdc3f --- /dev/null +++ b/xpa/man/mann/xpaoom.n @@ -0,0 +1,166 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpaoom n" +.TH xpaoom n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXpaoom: What happens when \s-1XPA\s0 runs out of memory?\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +When \s-1XPA\s0 can't allocate memory, it exits. You can arrange to have it call +\&\fIlongjmp()\fR instead. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +When an \s-1XPA\s0 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 \s-1OOM\s0 errors), you +can tell \s-1XPA\s0 to call \fIlongjmp()\fR to go to a recovery branch. To pass the +requisite jmp_buf variable to \s-1XPA\s0, make the following call: +.PP +.Vb 1 +\& XPASaveJmp(void *env); +.Ve +.PP +The value of env is the address of a jmp_buf variable that was previously +passed to \fIsetjmp()\fR. For example: +.PP +.Vb 9 +\& 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 ... +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpatcl.n b/xpa/man/mann/xpatcl.n new file mode 100644 index 0000000..9156d5e --- /dev/null +++ b/xpa/man/mann/xpatcl.n @@ -0,0 +1,362 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpatcl n" +.TH xpatcl n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPATcl: the \s-1XPA\s0 Interface to the Tcl/Tk Environment\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +Tcl/Tk programs can act as \s-1XPA\s0 clients and/or servers using the Tcl +interface to \s-1XPA\s0 that is contained in the libtclxpa.so shared object. +.PP +\&\fBServer Routines\fR +.PP +.Vb 11 +\& 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 +.Ve +.PP +\&\fBClient Routines\fR +.PP +.Vb 11 +\& 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] +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +You can call \fIXPANew()\fR, \fIXPACmdNew()\fR, or \fIXPAInfoNew()\fR within a C +routine to add C\-based \s-1XPA\s0 server callbacks to a TCL/Tk program that +uses a Tcl/Tk event loop (either \fIvwait()\fR or the Tk event loop); +Such a program does not need or want to use the \s-1XPA\s0 event loop. +Therefore, in order to add \s-1XPA\s0 access points to the Tcl/Tk loop, the +following routine should be called beforehand: +.PP +.Vb 1 +\& int XPATclAddInput(XPA xpa); +.Ve +.PP +Normally, the xpa argument is \s-1NULL\s0, meaning that all current \s-1XPA\s0 +access points are registered with the event loop. However, if a +single \s-1XPA\s0 access point is to be added (i.e., after the event loop is +started) then the handle of that \s-1XPA\s0 access point can be passed to +this routine. +.PP +The significance of the \s-1XPA/TCL\s0 interface goes beyond the support for +using \s-1XPA\s0 inside C code. The interface allows you to write \s-1XPA\s0 +servers and to make calls to the \s-1XPA\s0 client interface within the Tcl +environment using the Tcl language directly. The XPA/Tcl +interface can be loaded using the following package command: +.PP +.Vb 1 +\& package require tclxpa 2.0 +.Ve +.PP +Alternatively, you can load the shared object (called libtclxpa.so ) directly: +.PP +.Vb 1 +\& load .../libtclxpa.so tclxpa +.Ve +.PP +Once the tclxpa package is loaded, you can use Tcl versions of \s-1XPA\s0 +routines to define \s-1XPA\s0 servers or make client \s-1XPA\s0 calls. The +interface for these routines is designed to match the Unix \s-1XPA\s0 +interface as nearly as possible. Please refer to +\&\s-1XPA\s0 Servers +and +\&\s-1XPA\s0 Clients +for general information about these routines. +.PP +The file test.tcl in the \s-1XPA\s0 source directory gives examples for using the +XPA/Tcl interface. +.PP +The following notes describe the minor differences between the interfaces. +.PP +\&\fBXPANew\fR +.PP +.Vb 1 +\& set xpa [xpanew class name help sproc sdata smode rproc rdata rmode] +.Ve +.PP +rproc and sproc routines are routines. The calling sequence of the +rproc routine is identical to its C counterpart: +.PP +.Vb 1 +\& proc rec_cb { xpa client_data paramlist buf len } { ... } +.Ve +.PP +The sproc routine, however is slightly different from its C counterpart +because of the difficulty of passing data back from the callback to C: +.PP +.Vb 1 +\& proc sendcb { xpa client_data paramlist } { ... } +.Ve +.PP +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: +.PP +.Vb 1 +\& xpasetbuf xpa buf len +.Ve +.PP +where: +.PP +.Vb 5 +\& 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) +.Ve +.PP +When this routine is called, a copy of buf is saved for transmission to +the client. +.PP +The fact that buf is duplicated means that \s-1TCL\s0 server writers might wish to +perform the I/O directly within the callback, rather than have \s-1XPA\s0 do it +automatically at the end of the routine. To do this, set: +.PP +.Vb 1 +\& fillbuf=false +.Ve +.PP +in the xpanew smode and then perform I/O through the Tcl channel +obtained from: +.PP +.Vb 1 +\& set dchan [xparec $xpa datachan] +.Ve +.PP +where: +.PP +.Vb 5 +\& 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) +.Ve +.PP +\&\s-1NB:\s0 datachan and cmdchan are not available under Windows. It is +necessary to use the \*(L"raw\*(R" equivalents: datafd and cmdfd. +.PP +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 \*(L"fillbuf=false\*(R" in the rmode and then +reading the incoming data from datachan. +.PP +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: +.PP +.Vb 1 +\& return ?\-code c? ?\-errorinfo i? ?\-errorcode ec? string +.Ve +.PP +See the Tcl man page for more info. +.PP +\&\fBXPARec\fR +.PP +The Tcl xparec procedure supplies server routines with access to information +that is available via macros in the C interface: +.PP +.Vb 1 +\& set val [xparec xpa <option>] +.Ve +.PP +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 \*(L"version\*(R" can be used to +determine the \s-1XPA\s0 version used to build the Tcl interface. Note that +the standard options require a valid \s-1XPA\s0 handle, but \*(L"version\*(R" does +not (since it simply reports the value of the \s-1XPA_VERSION\s0 definition +in the \s-1XPA\s0 source include file). +.PP +\&\s-1NB:\s0 datachan and cmdchan are not available under Windows. It is +necessary to use the \*(L"raw\*(R" equivalents: datafd and cmdfd. +.PP +.Vb 12 +\& 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 +.Ve +.PP +Under Windows, the Tcl event handler cannot automatically sense when an +\&\s-1XPA\s0 socket is ready for \s-1IO\s0 (i.e. \fITcl_CreateFileHandler()\fR is not available +under Windows). The Windows Tcl event handler therefore must be awakened +occasionally for check for \s-1XPA\s0 events. This is done using the standard +\&\fITcl_SetMaxBlockTime()\fR call. The time parameter is defined in tclloop.c +and is currently set to 1000 microseconds (1/1000 of a second). +.PP +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: +.PP +.Vb 5 +\& if [catch { xparec "" version } version] { +\& puts "pre\-2.1.0e" +\& } else { +\& puts [split $version .] +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpatemplate.n b/xpa/man/mann/xpatemplate.n new file mode 100644 index 0000000..f8fc55a --- /dev/null +++ b/xpa/man/mann/xpatemplate.n @@ -0,0 +1,232 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpatemplate n" +.TH xpatemplate n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPATemplate: Access Point Names and Templates\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\s-1XPA\s0 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. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +When \s-1XPA\s0 servers call +\&\fIXPANew()\fR, +or +\&\fIXPACmdNew()\fR +to define \s-1XPA\s0 access points, they specify a string identifier composed of a +class and a name. When clients communicate with \s-1XPA\s0 access points, +they specify which access points to communicate with using +an identifier of the form: +.PP +.Vb 1 +\& class:name +.Ve +.PP +All registered \s-1XPA\s0 access points that match the specified identifier +will be available for communication (subject to access control rules, +etc.) +.PP +As of \s-1XPA\s0 2.1.5, the length of both the class and name designations are +limited to 1024 characters. +.PP +The \s-1XPA\s0 class:name identifier actually is a template: it accepts wild +cards in its syntax, so a single specifier can match more than one \s-1XPA\s0 +access point. (Note that the class is optional and defaults to \*(L"*\*(R".) +The allowed syntax for clients to specify the class:name template is +of the form shown below. (Note that \*(L"*\*(R" is used to denote a generic +wild card, but other wild cards characters are supported, as described +below). +.PP +.Vb 7 +\& 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 +.Ve +.PP +In general, the following wild-cards can be applied to class and name: +.PP +.Vb 5 +\& wildcard explanation +\& \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& ? match any character, but there must be one +\& * match anything, or nothing +\& [...] match an inclusive set +.Ve +.PP +Although the class:name template normally is used to refer to \s-1XPA\s0 +access points, these also can be specified using their individual +socket identifiers. For inet sockets, the socket identifier is +\&\fBip:port\fR, where ip can be the DNS-registered name, +the \s-1ASCII\s0 \s-1IP\s0 number (e.g. 123.45.67.890) or the hex \s-1IP\s0 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: +.PP +.Vb 2 +\& csh> xpaget xpans +\& DS9 ds9 gs saord.harvard.edu:3236 eric +.Ve +.PP +You can access ds9 using ip:3236 in any of the three forms: +.PP +.Vb 2 +\& 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 +.Ve +.PP +In the case of unix sockets, the socket identifier is a file: +.PP +.Vb 2 +\& 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 +.Ve +.PP +This feature can be useful in distinguishing between multiple +instances of a program that all have the same class:name designation. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpausers.n b/xpa/man/mann/xpausers.n new file mode 100644 index 0000000..2823e3d --- /dev/null +++ b/xpa/man/mann/xpausers.n @@ -0,0 +1,186 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpausers n" +.TH xpausers n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAUsers: Distinguishing Users\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\s-1XPA\s0 normally distinguishes between users on a given host, but it is possible +to send data to access points belonging to other users. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +A single \s-1XPA\s0 name service typically serves all users on a given +machine. Two users can register the same \s-1XPA\s0 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: +.PP +.Vb 4 +\& XPA xpa1 gs 838e2f67:1262 eric +\& XPA xpa2 gs 838e2f67:1266 eric +\& XPA xpa1 gs 838e2f67:2523 john +\& XPA xpa2 gs 838e2f67:2527 john +.Ve +.PP +Here the users \*(L"eric\*(R" and \*(L"john\*(R" both have registered the access +points xpa1 and xpa2. When either \*(L"john\*(R" or \*(L"eric\*(R" retrieves +information from xpa1, they will process only the access point +registered in their user name. +.PP +If you want to access another user's \s-1XPA\s0 access points on a single +machine, use the \-u [user] option on xpaset, xpaget, etc. For example, +if eric executes: +.PP +.Vb 1 +\& xpaget \-u john xpa1 +.Ve +.PP +he will access John's xpa1 access point.Use \*(L"*\*(R" to access all users +on a given machine: +.PP +.Vb 1 +\& xpaget \-u "*" xpa1 +.Ve +.PP +Note that the \s-1XPA\s0 Environment Variable +\&\s-1XPA_NSUSERS\s0 can be used to specify the default list of users to +process: +.PP +.Vb 1 +\& setenv XPA_NSUSERS "eric,john" +.Ve +.PP +will cause access points from both \*(L"eric\*(R" and \*(L"john\*(R" to be processed +by default. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/mann/xpaxt.n b/xpa/man/mann/xpaxt.n new file mode 100644 index 0000000..8885dd4 --- /dev/null +++ b/xpa/man/mann/xpaxt.n @@ -0,0 +1,161 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpaxt n" +.TH xpaxt n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAXt: the \s-1XPA\s0 Interface to Xt (X Windows)\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +Describes how \s-1XPA\s0 access points can be added to X Toolkit (Xt) programs. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1XPA\s0 supports Xt programs: you can call \fIXPANew()\fR, \fIXPACmdNew()\fR, or +\&\fIXPAInfoNew()\fR within any C routine to add \s-1XPA\s0 server callbacks to an Xt +program. Since an Xt program has its own event loop call (i.e., +\&\fIXtAppMainLoop()\fR), it therefore does not need or want to use the \s-1XPA\s0 +even loop. Thus, in order to add \s-1XPA\s0 access points to the standard Xt +event loop, the following routine should be called before entering the +loop: +.PP +.Vb 1 +\& int XPAXtAddInput(XtAppContext app, XPA xpa) +.Ve +.PP +The \fIXPAAddAddInput()\fR routine will add \s-1XPA\s0 access points to the Xt event +loop by making calls to the standard \fIXtAppAddInput()\fR routine. (If the +XtAppContext argument is \s-1NULL\s0, then the alternate \fIXtAddInput()\fR routine +is used instead.) If the xpa argument is \s-1NULL\s0, then all active \s-1XPA\s0 +access points are added to the loop. If xpa is not \s-1NULL\s0, 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 \fIXtAppMainLoop()\fR even loop. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages |