diff options
Diffstat (limited to 'xpa/man')
45 files changed, 10094 insertions, 0 deletions
diff --git a/xpa/man/man1/xpaaccess.1 b/xpa/man/man1/xpaaccess.1 new file mode 100644 index 0000000..a3aa7a6 --- /dev/null +++ b/xpa/man/man1/xpaaccess.1 @@ -0,0 +1,198 @@ +.\" 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 "xpaaccess 1" +.TH xpaaccess 1 "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" +\&\fBxpaaccess: see if template matches registered \s-1XPA\s0 access points\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +xpaaccess [\-c] [\-h] [\-i nsinet] [\-m method] [\-n] [\-t sval,lval] [\-u users] \-v <template> [type] +.SH "OPTIONS" +.IX Header "OPTIONS" +.Vb 10 +\& \-c contact each access point individually +\& \-h print help message +\& \-i access XPA point on different machine (override XPA_NSINET) +\& \-m override XPA_METHOD environment variable +\& \-n return number of matches instead of "yes" or "no" +\& \-t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) +\& \-u [users] XPA points can be from specified users (override XPA_NSUSERS) +\& \-v print info about each successful access point +\& \-V print info or error about each access point +\& \-\-version display version and exit +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +xpaaccess returns \*(L"yes\*(R" to stdout (with a return error code if 1) if there are +existing \s-1XPA\s0 access points that match the +template +(and optional access type: g,i,s). Otherwise, it returns \*(L"no\*(R" (with a +return error code of 0). If \-n is specified, the number of matches is +returned instead (both to stdout and in the returned error code). If +\&\-v is specified, each access point is displayed to stdout instead of +the number of matches. +.PP +By default, xpaaccess simply contacts the xpans name server to find +the list of registered access points that match the specified +template. It also checks to make sure the specified types are +supported by that access point. This is the fastest way to determine +available access points. However, an access point might registered but +not yet available, if, for example, the server program has not entered +its event loop to process \s-1XPA\s0 requests. To find access points that are +guaranteed to be available for processing, use the \-c (contact) +switch. With this switch, xpaaccess contacts each matching \s-1XPA\s0 server +(rather than the name server) to make sure the registered access point +really is ready for processing. In this mode, if an access point is +registered but not available, xpaaccess will pause for a period of +time equal to the \s-1XPA_LONG_TIMEOUT\s0, in order to give the server a +chance to ready itself. By default, this timeout is 30 seconds. You +can shorten the time of delay using the \-t \*(L"short,long\*(R" switch. For +example, to shorten the delay time to 2 seconds, use: +.PP +.Vb 1 +\& xpaaccess \-c \-t "2,2" ds9 +.Ve +.PP +The first argument is the short delay value, and is ignored in this +operation. The second is the long delay timeout. +.PP +Note also that the default xpaaccess method (no \-c switch) does not +check access control (acls) but rather only checks whether the access +point is both registered with the xpans name server and provides the +specified type of access. In other words, the default xpaaccess could +return 'yes' when you might not actually have access. This mode also +always returns 'yes' for the xpans name server itself, regardless of +whether the name server is active. The \-c (contact) switch, which +contacts the access point directly, can and does check the access +control (only for servers using version 2.1 and above) and also +returns the real status of xpans. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man1/xpachanges.1 b/xpa/man/man1/xpachanges.1 new file mode 100644 index 0000000..f910bbe --- /dev/null +++ b/xpa/man/man1/xpachanges.1 @@ -0,0 +1,180 @@ +.\" 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 "xpachanges 1" +.TH xpachanges 1 "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 Changes: Changes For Users from \s-1XPA\s0 1.0 and 2.0\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +This document describes changes that will affect users who migrate +from \s-1XPA\s0 1.0 to \s-1XPA\s0 2.0. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +There have been a few changes that affect users who upgrade \s-1XPA\s0 +from version 1.0 to version 2.0. These changes are detailed below. +.IP "\(bu" 4 +\&\s-1XPA\s0 commands no longer have a resolver routine (this is open to +negotiations, but we decided the idea was dumb). For the SAOtng +program, this means that you must explicitly specify the access +point, i.e.,: +.Sp +.Vb 1 +\& cat foo.fits | xpaset SAOtng fits +.Ve +.Sp +instead of: +.Sp +.Vb 1 +\& cat foo.fits | xpaset SAOtng +.Ve +.IP "\(bu" 4 +By default, xpaset, xpaget, etc. now wait for the server callback to +complete; i.e., the old \-W is implied (and the switch is ignored). +This allows support for better error handling. If you want xpaset, etc. +to return before the callback is complete, use \-n switch: +.Sp +.Vb 1 +\& echo "file foo.fits" | xpaset \-n SAOtng +.Ve +.IP "\(bu" 4 +The old \-w switch in xpaset and xpaget is no longer necessary (and is +ignored), since you can have more than one process communicating with +an xpa access point at one time. +.IP "\(bu" 4 +The new \-p switch on xpaset means you need not read from stdout: +.Sp +.Vb 1 +\& xpaset \-p SAOtng colormap I8 +.Ve +.Sp +will send the paramlist to the SAOtng callback without reading from stdin. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man1/xpaget.1 b/xpa/man/man1/xpaget.1 new file mode 100644 index 0000000..12d94d9 --- /dev/null +++ b/xpa/man/man1/xpaget.1 @@ -0,0 +1,164 @@ +.\" 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 "xpaget 1" +.TH xpaget 1 "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" +\&\fBxpaget: retrieve data from one or more \s-1XPA\s0 servers\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +xpaget [\-h] [\-i nsinet] [\-m method] [\-s] [\-t sval,lval] [\-u users] <template|host:port> [paramlist] +.SH "OPTIONS" +.IX Header "OPTIONS" +.Vb 8 +\& \-h print help message +\& \-i access XPA point on different machine (override XPA_NSINET) +\& \-m override XPA_METHOD environment variable +\& \-n don\*(Aqt wait for the status message after server completes +\& \-s enter server mode +\& \-t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) +\& \-u [users] XPA points can be from specified users (override XPA_NSUSERS) +\& \-\-version display version and exit +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Data will be retrieved from access points matching the +template +or host:port. +A set of qualifying parameters can be appended. +.PP +\&\fBExamples:\fR +.PP +.Vb 2 +\& csh> xpaget ds9 images +\& csh> xpaget myhost.harvard.edu:12345 +.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/man1/xpainfo.1 b/xpa/man/man1/xpainfo.1 new file mode 100644 index 0000000..2ad7f81 --- /dev/null +++ b/xpa/man/man1/xpainfo.1 @@ -0,0 +1,163 @@ +.\" 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 "xpainfo 1" +.TH xpainfo 1 "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" +\&\fBxpainfo: send short message to one or more \s-1XPA\s0 servers\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +xpainfo [\-h] [\-i nsinet] [\-m method] [\-n] [\-s] [\-t sval,lval] [\-u users] <template|host:port> [paramlist] +.SH "OPTIONS" +.IX Header "OPTIONS" +.Vb 8 +\& \-h print help message +\& \-i access XPA point on different machine (override XPA_NSINET) +\& \-m override XPA_METHOD environment variable +\& \-n don\*(Aqt wait for the status message after server completes +\& \-s enter server mode +\& \-t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) +\& \-u [users] XPA points can be from specified users (override XPA_NSUSERS) +\& \-\-version display version and exit +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Info will be sent to access points matching the +template +or host:port. +A set of qualifying parameters can be appended. +.PP +\&\fBExamples:\fR +.PP +.Vb 1 +\& csh> xpainfo IMAGE ds9 image +.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/man1/xpamb.1 b/xpa/man/man1/xpamb.1 new file mode 100644 index 0000000..37f06f4 --- /dev/null +++ b/xpa/man/man1/xpamb.1 @@ -0,0 +1,325 @@ +.\" 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 "xpamb 1" +.TH xpamb 1 "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" +\&\fBxpamb: the \s-1XPA\s0 Message Bus\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +The xpamb program can act as a \*(L"classical\*(R" message bus interface +between clients and servers. A client can send a data request to +the message bus, which then interfaces with multiple servers and +returns the data back to the client. +.SH "OPTIONS" +.IX Header "OPTIONS" +For xpaset, several optional switches are used to save data and +manipulate the stored data: +.IP "\(bu" 4 +\&\fB\-data [name]\fR +.Sp +Add the supplied data buffer to a pool of stored data buffers, +using the specified name as a unique identifier for later retrieval. +An error occurs if the name already exists (use either \fBreplace\fR +or \fBdel\fR to rectify this). The \fB\-add\fR switch is supported +for backwards compatibility with xpa 2.0. +.IP "\(bu" 4 +\&\fB\-replace [name]\fR +.Sp +Replace previously existing stored data having the same unique name +with new data. This essentially is a combination of the \fBdel\fR +and \fBdata\fR commands. +.IP "\(bu" 4 +\&\fB\-info [\*(L"'info string'\*(R"]\fR +.Sp +When adding a data buffer, you can specify an informational +string to be stored with that data. This string will be returned +by xpaget: +.Sp +.Vb 1 +\& xpaget xpamb foo \-info +.Ve +.Sp +(along with other information such as the date/time of storage and the size of +the data buffer) if the \-info switch is specified. If the info string contains +spaces, you must enclose it in \fBtwo\fR sets of quotes: +.Sp +.Vb 1 +\& cat foo | xpaset xpamb \-store foo \-info "\*(Aqthis is info on foo\*(Aq" +.Ve +.Sp +The first set of quotes is removed by the shell while the second is used to +delineate the info string. +.IP "\(bu" 4 +\&\fB\-send [name]\fR +.Sp +Broadcast the stored data buffer to the named template. +.IP "\(bu" 4 +\&\fB\-del [name]\fR +.Sp +Delete the named data buffer and free all allocated space. +.PP +Switches can be used in any combination that makes sense. For example: +.PP +.Vb 1 +\& cat foo.fits | xpaset xpamb \-store foo \-info "FITS" "DS9:*" fits foo.fits +.Ve +.PP +will broadcast the foo.fits image to all access points of class +\&\fB\s-1DS9\s0\fR. In addition, the foo.fits file will be stored under the +name of \fBfoo\fR for later manipulation such as: +.PP +.Vb 1 +\& xpaset \-p xpamb \-send foo "DS9:*" fits foo.fits +.Ve +.PP +will re-broadcast the foo.fits image to all access points of class \*(L"\s-1DS9\s0\*(R". +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +A \*(L"classical\*(R" message bus (such as ToolTalk) consists of servers and +clients, along with a mediating program that transfers data between +different processes. \s-1XPA\s0 takes a slightly different approach in that +communication between clients and servers is direct. This generally +is the correct technique when there is only one connection (or even a +small number of connections), but can become inefficient for the +serving program if a large amount of data is being transferred to many +clients. For example, if a real-time data acquisition program is +broadcasting a \s-1FITS\s0 image to several clients, it would need to +transmit that image to each client individually. This might interfere +with its own processing cycles. The preferable mechanism would be to +pass the image off to an intermediate program that can then broadcast +the data to the several clients. +.PP +The \fBxpamb\fR program can alleviate such problems by functioning +as a message bus in cases where such an intermediary process is +wanted. It pre-defines a single access point named +\&\fBXPAMB:xpamb\fR to which data can be sent for re-broadcast. You +also can tell \fBxpamb\fR to save the data, and associate with that +data a new access point, so that it can be retrieved later on. +.PP +All interaction with \fBxpamb\fR is performed through +\&\fBxpaset\fR and \fBxpaget\fR (or the corresponding \s-1API\s0 +routines, \fB\f(BIXPASet()\fB\fR and \fB\f(BIXPAGet()\fB\fR) to the +\&\fBXPAMB:xpamb\fR access point. That is, \fBxpamb\fR is just +another XPA-enabled program that responds to requests from +clients. The paramlist is used to specify the targets to which +the data will be for re-broadcast, as well as the re-broadcast paramlist: +.PP +.Vb 1 +\& data | xpaset xpamb [switches] broadcast\-target broadcast\-paramlist +.Ve +.PP +Optional switches are used to store data, and manipulate stored data, +and are described below. +.PP +In its simplest form, you can, for example, send a \s-1FITS\s0 image to xpamb for +broadcasting to all ds9 image simply by executing: +.PP +.Vb 1 +\& cat foo.fits | xpaset xpamb "DS9:*" fits foo.fits +.Ve +.PP +Since \fB\s-1DS9\s0\fR is the class name for the ds9 image display +program, this will result in the \s-1FITS\s0 image being re-sent to all fits +access points for all active image display programs. +.PP +You can send stored data and new data to the same set of access points at +the same time. The stored data always is send first, followed by the new +data: +.PP +.Vb 1 +\& cat foo2.fits | xpaset xpamb \-send foo "DS9:*" fits foo.fits +.Ve +.PP +will first send the foo.fits file, and then the foo2.fits file to all +access points of class \fB\s-1DS9\s0\fR. Notice that in this example, +the foo2.fits file is not stored, but it could be stored by using the +\&\fB\-store [name]\fR switch on the command line. +.PP +The \fBxpaget\fR command can be used to retrieve a data from \s-1XPA\s0 +access points or from a stored data buffer, or retrieve information +about a stored data buffer. If no arguments are given: +.PP +.Vb 1 +\& xpaget xpamb +.Ve +.PP +then information about all currently stored data buffers is returned. This +information includes the data and time at which the data was stored, the +size in bytes of the data, and the supplied info string. +.PP +If arguments are specified, they will be in the form: +.PP +.Vb 1 +\& xpaget xpamb [\-info] [\-data] [name [paramlist]] +.Ve +.PP +If the optional \fB\-info\fR and/or \fB\-data\fR switches are specified, then +information and/or data will be returned for the named data buffer +following the switches. You can use either or both of these switches +in a single command. For example, if the \-info switch is used: +.PP +.Vb 1 +\& xpaget xpamb \-info foo +.Ve +.PP +then the info about that stored data buffer will be returned. +If the \-data is used with a specific name: +.PP +.Vb 1 +\& xpaget xpamb \-data foo +.Ve +.PP +then the stored data itself will be returned. If both are used: +.PP +.Vb 1 +\& xpaget xpamb \-info \-data foo +.Ve +.PP +then the info will be returned, followed by the data. Note that it is an +error to specify one of these switches without a data buffer name and that +the paramlist will be ignored. +.PP +If neither the \fB\-info\fR or \fB\-data\fR switch is specified, then +the name refers to an \s-1XPA\s0 access point (with an optional paramlist +following). +For example: +.PP +.Vb 1 +\& xpaget xpamb ds9 file +.Ve +.PP +is equivalent to: +.PP +.Vb 1 +\& xpaget ds9 file +.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/man1/xpans.1 b/xpa/man/man1/xpans.1 new file mode 100644 index 0000000..3573725 --- /dev/null +++ b/xpa/man/man1/xpans.1 @@ -0,0 +1,331 @@ +.\" 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 "xpans 1" +.TH xpans 1 "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" +\&\fBxpans: the \s-1XPA\s0 Name Server\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& xpans [\-h] [\-e] [\-k sec] [\-p port] [\-l log] [\-s security log] [\-P n] +.Ve +.SH "OPTIONS" +.IX Header "OPTIONS" +.Vb 8 +\& \-h print help message +\& \-e exit when there are no more XPA connections +\& \-k send keepalive messages every n sec +\& \-l log data base entries to specified file +\& \-p listen for connections on specified port +\& \-s log security info for each connection to specified file +\& \-P accept proxy requests (P=1) using separate thread (P=2) +\& \-\-version display version and exit +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The xpans name server is an XPA-enabled program that is used to +manage the names and ports of \s-1XPA\s0 access points. It is started +automatically when an \s-1XPA\s0 access point is registered. You can access +the name server using xpaget to get a list of registered access points. +.PP +The \fIxpans\fR name server provides a crucial link between \s-1XPA\s0 +clients and servers. When an \s-1XPA\s0 server defines an access point using +\&\fIXPANew()\fR, \fIXPACmdNew()\fR, or \fIXPAInfoNew()\fR, the name of the access point +is registered in the name service, along with connection information. +The name server then matches class:name templates passed to it by \s-1XPA\s0 +clients with these registered entries, so that the clients can +communicate with the appropriate servers. +.PP +The socket connection between an XPA-enabled program and +\&\fIxpans\fR is kept open until the former exits (or explicitly +closes the connection). Apparently, some Internet equipment (e.g. \s-1DSL\s0 +modems) can cause such a connection to time-out after a period of +inactivity. To prevent this from happening, you can use the \-k +[sec] switch to send a short keep-alive message to each open +connection after the specified time delay. (Note that this +application level use of keep-alive is necessary only if you are +serving XPA-enabled clients over the Internet and have to deal with +long-term connections involving \s-1DSL\s0 or similar equipment. \s-1XPA\s0 uses +the ordinary socket-level keep-alive, which works for all other cases.) +\&\s-1NB\s0 (12/2/2009): Out-of-band (\s-1URG\s0) \s-1TCP\s0 data, used by xpans +keep-alive, is changed by some Cisco routers into in-band data. +Encountering such a router will break the keep-alive function and may +break your \s-1XPA\s0 server as well. Proceed with caution! +.PP +The \fIxpans\fR program will be started automatically (assuming it +can be found in the user's path) when the first \s-1XPA\s0 access point is +registered. It therefore need not be started explicitly. However, +when started automatically, the \fI\-e\fR switch is used, so that +the name server will exit when there are no more \s-1XPA\s0 access points +registered. If you wish to keep the name server running continually, +simply start it manually without the \fI\-e\fR switch. +.PP +The name server will keep a log of registered access points if the +\&\fI\-l [log]\fR switch is used on the command line (this is the +case for automatic start-up). The log contains enough name and connection +information to allow you to re-register all \s-1XPA\s0 access points in case +the name server process is terminated prematurely. For example, after +the ds9 access point is registered,the log will contain the entry: +.PP +.Vb 1 +\& add 838e2f67:1863 ds9 ds9 gs eric +.Ve +.PP +If \fIxpans\fR is terminated but ds9 still is running, you +can re-register both access points for the ds9 process by running: +.PP +.Vb 1 +\& xpaset \-p 838e2f67:1863 \-nsconnect +.Ve +.PP +Notice that the ip:port specifier is used with \fIxpaset\fR to bypass +the need for contacting the name server (which does not have the name +registered yet!) +.PP +The name server will keep a log of security information if the \-s +[security log] switch is used on the command line. For each +accepted connection, (including connections via the \fIxpaget\fR +command), information will be logged about the host issuing the +command and the parameters passed into the program. This is most +useful when \fIxpans\fR is accepting connections from untrusted +machines. +.PP +When an \s-1XPA\s0 access point is removed by a server using \fI\fIXPAFree()\fI\fR, +the access information is removed from the name server. If an +XPA-enabled process is terminated, all names registered by that process +will be removed automatically. The log file is always updated to +reflect the currently registered access points. +.PP +The name server itself has an \s-1XPA\s0 access point names \fIxpans\fR +registered through which you can find out information about currently +registered access points (assuming you have access to the name server; +see \s-1XPA\s0 Access Control for more information). +For each registered access point, the following information is returned: +.PP +.Vb 5 +\& class # class of the access point +\& name # name of the access point +\& access # allowed access (g=xpaget,s=xpaset,i=xpainfo) +\& id # socket access method (host:port for inet, file for local/unix) +\& user # user name of access point owner +.Ve +.PP +For example, to display all currently registered access points, simply execute: +.PP +.Vb 1 +\& xpaget xpans +.Ve +.PP +Continuing the example of ds9 above, this will return: +.PP +.Vb 1 +\& DS9 ds9 gs 838e2f67:1863 eric +.Ve +.PP +If the same program has been started with different \s-1XPA\s0 access names, +you can look up only names matching a specified template. For example, +assume that ds9 has been started up using: +.PP +.Vb 3 +\& ds9 & +\& ds9 \-title ds9\-1\-eric & +\& ds9 \-title ds9\-2\-eric & +.Ve +.PP +To lookup all ds9 access points which end in \*(L".eric\*(R" and which can +be accessed using \fIxpaset\fR, use: +.PP +.Vb 1 +\& xpaget xpans "DS9:*.eric" "s" "*" +.Ve +.PP +This will return: +.PP +.Vb 2 +\& DS9 ds9\-2\-eric gs 838e29d3:42102 eric +\& DS9 ds9\-1\-eric gs 838e29d3:42105 eric +.Ve +.PP +The third argument \*(L"*\*(R" requests all access points from all users. +You also can specify a specific user name and only access points +registered by that user will be returned. +.PP +The name server uses the \fI\s-1XPA_METHOD\s0\fR environment variable +to determine whether it should listen for requests on \s-1INET\s0 or \s-1LOCAL\s0 +sockets. Since \s-1XPA\s0 access points also use this environment variable, +the choice of socket method will be consistent. Note that, when \s-1INET\s0 +sockets are used, a local server can be accessed from remote machines +if the \fI\s-1XPA_NSINET\s0\fR environment variable is set to point to +the local machine. See +\&\s-1XPA\s0 Environment Variables +for more information. +.PP +An experimental feature of xpans is its ability to act as a proxy to +\&\s-1XPA\s0 servers behind firewalls that want to communicate with external +processes. The basic idea is the following: an \s-1XPA\s0 server (call it +\&\*(L"foo\*(R") on host1, possibly behind a firewall, makes a remote connection +to a proxy-enabled xpans program on host2 (specifying host2's \s-1XPA\s0 method). +For example: +.PP +.Vb 1 +\& xpaset \-p foo \-remote \*(Aqhost2:28571\*(Aq + \-proxy # on host1 +.Ve +.PP +When this is done, host2 can use xpaset, xpaget, and xpainfo calls to +communicate with the \s-1XPA\s0 server foo. All command communication is +performed via the xpans socket connection between foo on host1 and +xpans on host2 (which was initiated by foo from inside the firewall). +Data communication is similarly performed using a socket connection +initiated on host1 (usually with a port value two greater than the +port value of the main xpans socket connection). An xpaset or xpaget +call on host2 contacts xpans, which performs an \fIXPASet()\fR or \fIXPAGet()\fR +call to foo, passing commands and data back and forth between the two +programs. +.PP +By default, proxy connections are not allowed by xpans. If the \-P switch is +specified with a value of 1, proxy connection are allowed, but all proxy +communication is performed in the same thread as xpans processing. If +a value of 2 is specified, the proxy processing is performed in a +separate thread (assuming pthreads are supported on your system). +Because xpa callback processing of any type can take a long time and +therefore can interfere with normal xpans processing, threaded proxy +connections (\-P 2) are recommended. When using proxy connections, it +might also be useful to set the \s-1XPA_IOCALLSXPA\s0 environment variable, so +that multiple proxy requests can be handled at the same time, instead of +serially. +.PP +Note that this proxy interface to xpans is experimental. It is used +to provide remote data analysis capabilities on the Chandra-Ed system +using ds9. (See http://chandra\-ed.cfa.harvard.edu and +http://hea\-www.harvard.edu/saord/ds9 for more details). As always, please +contact us if you have problems or questions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man1/xpaset.1 b/xpa/man/man1/xpaset.1 new file mode 100644 index 0000000..943a708 --- /dev/null +++ b/xpa/man/man1/xpaset.1 @@ -0,0 +1,217 @@ +.\" 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 "xpaset 1" +.TH xpaset 1 "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" +\&\fBxpaset: send data to one or more \s-1XPA\s0 servers\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +<data> | xpaset [\-h] [\-i nsinet] [\-m method] [\-n] [\-p] [\-s] [\-t sval,lval] [\-u users] [\-v] <template|host:port> [paramlist] +.SH "OPTIONS" +.IX Header "OPTIONS" +.Vb 10 +\& \-h print help message +\& \-i access XPA point on different machine (override XPA_NSINET) +\& \-m override XPA_METHOD environment variable +\& \-n don\*(Aqt wait for the status message after server completes +\& \-p don\*(Aqt read (or send) buf data from stdin +\& \-s enter server mode +\& \-t [s,l] set short and long timeouts (override XPA_[SHORT,LONG]_TIMEOUT) +\& \-u [users] XPA points can be from specified users (override XPA_NSUSERS) +\& \-v verify message to stdout +\& \-\-version display version and exit +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Data read from stdin will be sent to access points matching the +template +or host:port. +A set of qualifying parameters can be appended. +.PP +Normally, xpaset reads data input from stdin until \s-1EOF\s0 and sends those +data to the \s-1XPA\s0 target, along with parameters entered on the command +line. For example to send a \s-1FITS\s0 file to the ds9 image display: +.PP +.Vb 1 +\& cat foo.fits | xpaset ds9 fits +.Ve +.PP +Sometimes, however, it is desirable to send only parameters to an \s-1XPA\s0 +access point, without sending data. For such cases, use the \-p switch to +indicate that there is no data being send to stdin. For example, to +change the colormap used by the ds9 image display program, use: +.PP +.Vb 1 +\& csh> xpaset \-p ds9 cmap Heat +.Ve +.PP +Of course, this also can be accomplished by sending \s-1EOF\s0 to stdin in +any of the usual ways: +.PP +.Vb 4 +\& csh> echo "" | xpaset ds9 cmap Heat +\& csh> xpaget ds9 cmap Heat < /dev/null +\& csh> xpaset ds9 cmap Heat +\& ^D # Ctl\-D signals EOF +.Ve +.PP +The \-s switch puts xpaset into server mode, in which commands and data +can be sent to access points without having to run xpaset multiple times. +(Its not clear if this buys you much!) The syntax for sending commands +in server mode is: +.PP +.Vb 8 +\& csh> xpaset \-s +\& xpaset ds9 colormap I8 +\& ^D +\& xpaset ds9 regions +\& circle 200 300 40 +\& circle 300 400 50 +\& ^D +\&etc. +.Ve +.PP +After the required \*(L"xpaset\*(R" command is specified, optional \s-1ASCII\s0 data +can be appended (as in the region example). A single data/command set is +delimited by ^D. Note that typing ^D when a command is expected terminates +the program. +.PP +\&\s-1NB:\s0 server mode only works from the terminal and only \s-1ASCII\s0 data can be +sent in this way. +.PP +\&\fBExamples:\fR +.PP +.Vb 2 +\& csh> xpaset ds9 file < foo.fits +\& csh> echo "stop" | xpaset myhost:12345 +.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/man3/xpaaccess.3 b/xpa/man/man3/xpaaccess.3 new file mode 100644 index 0000000..a7e25e8 --- /dev/null +++ b/xpa/man/man3/xpaaccess.3 @@ -0,0 +1,233 @@ +.\" 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 "xpaaccess 3" +.TH xpaaccess 3 "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" +XPAAccess: return XPA access points matching +template (XPA 2.1 and above) +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& int XPAAccess(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& char **names, char **messages, int n); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The XPAAccess routine returns the public access points that match the +specified second argument template and +have the specified access type. +.PP +A +template +of the form \*(L"class1:name1\*(R" is sent to the +\&\s-1XPA\s0 name server, which returns a list of at most n matching \s-1XPA\s0 +servers. A connection is established with each of these servers and +the paramlist string is passed to the server as the data transfer +request is initiated. If an \s-1XPA\s0 struct is passed to the call, then the +persistent connections are updated as described above. Otherwise, +temporary connections are made to the servers (which will be closed +when the call completes). +.PP +The \fIXPAAccess()\fR routine retrieves names from at most n \s-1XPA\s0 servers +that match the specified template and that were checked for access +using the specified mode. The return string contains both the +class:name and ip:port. If a given server returned an error or the +server callback sends a message back to the client, then the message +will be stored in the associated element of the messages array. +\&\s-1NB:\s0 if specified, the name and messages arrays must be of size n or greater. +.PP +The returned message string will be of the form: +.PP +.Vb 1 +\& XPA$ERROR error\-message (class:name ip:port) +.Ve +.PP +Note that names of matching registered access points are always +returned but may not be valid; it is not sufficient to assume that the +returned number of access points is the number of valid access points. +Rather, it is essential to check the messages array for error +messages. Any string in the messages array is an error message and +indicated that the associated access point is not available. +.PP +For example, assume that a server registers a number of access points +but delays entering its event loop. If a call to \fIXPAAccess()\fR is made +before the event loop is entered, the call will timeout (after waiting +for the long timeout period) and return an error of the form: +.PP +.Vb 1 +\& XPA$ERROR: timeout waiting for server authentication (XPA:xpa1) +.Ve +.PP +The error means that the \s-1XPA\s0 access point has been registered but is +not yet available (because events are not being processed). When the +server finally enters its event loop, subsequent calls to \fIXPAAccess()\fR +will return successfully. +.PP +\&\s-1NB:\s0 This routine only works with \s-1XPA\s0 servers built with \s-1XPA\s0 2.1.x and later. +Servers with older versions of \s-1XPA\s0 will return the error message: +.PP +.Vb 1 +\& XPA$ERROR invalid xpa command in initialization string +.Ve +.PP +If you get this error message, then the old server actually is ready +for access, since it got to the point of fielding the query! The +xpaaccess program, for example, ignores this message in order to work +properly with older servers. +.PP +The third argument for \fIXPAAccess()\fR is the type of access and can be +any combination of: +.PP +.Vb 5 +\& type explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& g xpaget calls can be made on this access point +\& s xpaset calls can be made on this access point +\& i xpainfo calls can be made on this access point +.Ve +.PP +The mode string argument is of the form: \*(L"key1=value1,key2=value2,...\*(R" +The following keywords are recognized: +.PP +.Vb 3 +\& key value default explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& ack true/false true if false, don\*(Aqt wait for ack from server (after callback completes) +.Ve +.PP +The ack keyword is not very useful, since the server completes the callback +in order to return the data anyway. It is here for completion (and perhaps +for future usefulness). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpaatexit.3 b/xpa/man/man3/xpaatexit.3 new file mode 100644 index 0000000..4ff2c7d --- /dev/null +++ b/xpa/man/man3/xpaatexit.3 @@ -0,0 +1,149 @@ +.\" 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 "xpaatexit 3" +.TH xpaatexit 3 "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" +\&\fBXPAAtExit: install exit handler\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& void XPAAtExit(void); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fIXPAAtExit()\fR will install an exit handler using \fIatexit()\fR to run XPAFree on all +\&\s-1XPA\s0 access points. This might be useful in cases where Unix sockets are being +used: if an explicit call to \fIXPAFree()\fR is not made by the program, the Unix +socket file will not be deleted immediately without an atexit handler. (\s-1NB:\s0 this +call should not be made in a Tcl/Tk application. Accessing the Tcl native file +system after Tcl has shut down all file systems causes the Tcl/Tl program to +crash). diff --git a/xpa/man/man3/xpacleanup.3 b/xpa/man/man3/xpacleanup.3 new file mode 100644 index 0000000..57ec12e --- /dev/null +++ b/xpa/man/man3/xpacleanup.3 @@ -0,0 +1,151 @@ +.\" 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 "xpacleanup 3" +.TH xpacleanup 3 "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" +\&\fBXPACleanup: release reserved \s-1XPA\s0 memory\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& void XPACleanup(void); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +When \s-1XPA\s0 is initialized, it allocates a small amount of memory for the +access control list, temp directory path, and reserved commands. This +memory is found by valgrind to be \*(L"still reachable\*(R", meaning that \*(L"your +program didn't free some memory it could have\*(R". Calling the +\&\fIXPACleanup()\fR routine before exiting the program will free this memory +and make valgrind happy. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpaclient.3 b/xpa/man/man3/xpaclient.3 new file mode 100644 index 0000000..804f57b --- /dev/null +++ b/xpa/man/man3/xpaclient.3 @@ -0,0 +1,206 @@ +.\" 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 "xpaclient 3" +.TH xpaclient 3 "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" +\&\fBXPAClient: The \s-1XPA\s0 Client-side Programming Interface\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +A description of the \s-1XPA\s0 client-side programming interface. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBIntroduction to \s-1XPA\s0 Client Programming\fR +.PP +Sending/receiving data to/from an \s-1XPA\s0 access point is easy: you +generally only need to call the \fIXPAGet()\fR or \fIXPASet()\fR subroutines. +.PP +.Vb 1 +\& #include <xpa.h> +\& +\& int XPAGet(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& char **bufs, size_t *lens, char **names, char **messages, int n); +\& +\& int XPASet(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& char *buf, size_t len, char **names, char **messages, int n); +\& +\& int XPAInfo(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& char **names, char **messages, int n); +\& +\& int XPAAccess(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& char **names, char **messages, int n); +\& +\& int XPAGetFd(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& int *fds, char **names, char **messages, int n); +\& +\& int XPASetFd(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& int fd, char **names, char **messages, int n); +\& +\& XPA XPAOpen(char *mode); +\& +\& void XPAClose(XPA xpa); +\& +\& int XPANSLookup(XPA xpa, +\& char *template, char *type, +\& char ***classes, char ***names, char ***methods, char ***infos); +.Ve +.PP +\&\fBIntroduction\fR +.PP +To use the \s-1XPA\s0 application programming interface, a software developer +generally will include the xpa.h definitions file: +.PP +.Vb 1 +\& #include <xpa.h> +.Ve +.PP +in the software module that defines or accesses an \s-1XPA\s0 access point and +then will link against the libxpa.a library: +.PP +.Vb 1 +\& gcc \-o foo foo.c libxpa.a +.Ve +.PP +\&\s-1XPA\s0 has been compiled using both C and \*(C+ compilers. +.PP +Client communication with \s-1XPA\s0 public access points generally is +accomplished using \fIXPAGet()\fR or \fIXPASet()\fR within a program (or xpaget +and xpaset at the command line). Both routines require specification +of the name of the access point. If a template +is used to specify the access point name (e.g., \*(L"ds9*\*(R"), then +communication will take place with all servers matching that template. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpaclose.3 b/xpa/man/man3/xpaclose.3 new file mode 100644 index 0000000..15e5941 --- /dev/null +++ b/xpa/man/man3/xpaclose.3 @@ -0,0 +1,157 @@ +.\" 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 "xpaclose 3" +.TH xpaclose 3 "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" +\&\fBXPAClose: close a persistent \s-1XPA\s0 client handle\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& void XPAClose(XPA xpa); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +XPAClose closes the persistent connections associated with this \s-1XPA\s0 struct +and frees all allocated space. It also closes the open sockets connections +to all \s-1XPA\s0 servers that were opened using this handle. +.PP +\&\fBExample:\fR +.PP +.Vb 1 +\& #include <xpa.h> +\& +\& XPA xpa; +\& XPAClose(xpa); +.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/man3/xpacmdadd.3 b/xpa/man/man3/xpacmdadd.3 new file mode 100644 index 0000000..9c4b7e5 --- /dev/null +++ b/xpa/man/man3/xpacmdadd.3 @@ -0,0 +1,174 @@ +.\" 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 "xpacmdadd 3" +.TH xpacmdadd 3 "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" +\&\fBXPACmdAdd: add a command to an \s-1XPA\s0 command public access point\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& XPACmd XPACmdAdd(XPA xpa, char *name, char *help, +\& int (*send_callback)(), +\& void *send_data, char *send_mode, +\& int (*rec_callback)(), +\& void *rec_data, char *rec_mode); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Add a command to an \s-1XPA\s0 command access point. The \s-1XPA\s0 argument specifies the +\&\s-1XPA\s0 struct returned by a call to \fIXPANewCmd()\fR. The name argument is the +name of the command. The other arguments function identically to the +arguments in the \fIXPANew()\fR command, i.e., the send_callback and rec_callback +routines have identical calling sequences to their \fIXPANew()\fR counterparts, +with the exceptions noted below. +.PP +When help is requested for a command access point using: +.PP +.Vb 1 +\& xpaget \-h class:name +.Ve +.PP +all of the command help strings are listed. To get help for a given +command, use: +.PP +.Vb 1 +\& xpaget \-h class:name cmd +.Ve +.PP +Also, the acl keyword in the send_mode and receive_mode strings is +global to the access point, not local to the command. Thus, the value +for the acl mode should be the same in all send_mode (or receive_mode) +strings for each command in a command access point. (The acl for +send_mode need not be the same as the acl for receive_mode, though). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpacmddel.3 b/xpa/man/man3/xpacmddel.3 new file mode 100644 index 0000000..21bf0be --- /dev/null +++ b/xpa/man/man3/xpacmddel.3 @@ -0,0 +1,147 @@ +.\" 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 "xpacmddel 3" +.TH xpacmddel 3 "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" +\&\fBXPACmdDel: remove a command from an \s-1XPA\s0 command public access point\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& void XPACmdDel(XPA xpa, XPACmd cmd); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This routine removes a command from the list of available commands in +a given \s-1XPA\s0. That command will no longer be available for processing. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpacmdnew.3 b/xpa/man/man3/xpacmdnew.3 new file mode 100644 index 0000000..8a1cb94 --- /dev/null +++ b/xpa/man/man3/xpacmdnew.3 @@ -0,0 +1,196 @@ +.\" 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 "xpacmdnew 3" +.TH xpacmdnew 3 "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" +\&\fBXPACmdNew: create a new \s-1XPA\s0 public access point for commands\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& XPA XPACmdNew(char *class, char *name); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Create a new \s-1XPA\s0 public access point for commands that will share a +common identifier class:name. Enter this access point into the \s-1XPA\s0 +name server, so that it can be accessed by external processes. +\&\fIXPACmdNew()\fR returns an \s-1XPA\s0 struct. +.PP +It often is more convenient to have one public access point that can +manage a number of commands, rather than having individual access +points for each command. For example, it is easier to command the +ds9 image display using: +.PP +.Vb 3 +\& echo "colormap I8" | xpaset ds9 +\& echo "scale log" | xpaset ds9 +\& echo "file foo.fits" | xpaset ds9 +.Ve +.PP +then to use: +.PP +.Vb 3 +\& echo "I8" | xpaset ds9_colormap +\& echo "log" | xpaset ds9_scale +\& echo "foo.fits" | xpaset ds9_file +.Ve +.PP +In the first case, the commands remain the same regardless of the +target \s-1XPA\s0 name. In the second case, the command names must change +for each instance of ds9. That is, if a second instance of ds9 +called \s-1DS9\s0 were running, it would be commanded either as: +.PP +.Vb 3 +\& echo "colormap I8" | xpaset DS9 +\& echo "scale log" | xpaset DS9 +\& echo "file foo.fits" | xpaset DS9 +.Ve +.PP +or as: +.PP +.Vb 3 +\& echo "I8" | xpaset DS9_colormap +\& echo "log" | xpaset DS9_scale +\& echo "foo.fits" | xpaset DS9_file +.Ve +.PP +Thus, in cases where a program is going to manage many commands, it +generally is easier to define them as commands associated with the +\&\fIXPACmdNew()\fR routine, rather than as separate access points using +\&\fIXPANew()\fR. +.PP +When \fIXPACmdNew()\fR is called, only the class:name identifier is +specified. Each sub-command is subsequently defined using the +\&\fIXPACmdAdd()\fR routine. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpafree.3 b/xpa/man/man3/xpafree.3 new file mode 100644 index 0000000..53783eb --- /dev/null +++ b/xpa/man/man3/xpafree.3 @@ -0,0 +1,153 @@ +.\" 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 "xpafree 3" +.TH xpafree 3 "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" +\&\fBXPAFree: remove an \s-1XPA\s0 public access point\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& int XPAFree(XPA xpa); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Remove the specified \s-1XPA\s0 public access point from the name server and +free all associated storage. Note that removal from the name server +happens automatically when the process terminates, so this call is not +generally needed. It is used when public access points are being +defined temporarily and then destroyed when no longer needed. For +example, ds9 temporarily creates a public access point when it +loads a new image for display and destroys it when the image is +unloaded. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpaget.3 b/xpa/man/man3/xpaget.3 new file mode 100644 index 0000000..4f03cf6 --- /dev/null +++ b/xpa/man/man3/xpaget.3 @@ -0,0 +1,244 @@ +.\" 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 "xpaget 3" +.TH xpaget 3 "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" +\&\fBXPAGet: retrieve data from one or more \s-1XPA\s0 servers\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& int XPAGet(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& char **bufs, size_t *lens, char **names, char **messages, +\& int n); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Retrieve data from one or more \s-1XPA\s0 servers whose class:name identifier +matches the specified template. +.PP +A +template +of the form \*(L"class1:name1\*(R" is sent to the +\&\s-1XPA\s0 name server, which returns a list of at most n matching \s-1XPA\s0 +servers. A connection is established with each of these servers and +the paramlist string is passed to the server as the data transfer +request is initiated. If an \s-1XPA\s0 struct is passed to the call, then the +persistent connections are updated as described above. Otherwise, +temporary connections are made to the servers (which will be closed +when the call completes). +.PP +The \fIXPAGet()\fR routine then retrieves data from at most n \s-1XPA\s0 servers, +places these data into n allocated buffers and places the buffer +pointers in the bufs array. The length of each buffer is stored in the +lens array. A string containing the class:name and ip:port is stored +in the name array. If a given server returned an error or the server +callback sends a message back to the client, then the message will be +stored in the associated element of the messages array. \s-1NB:\s0 if +specified, the name and messages arrays must be of size n or greater. +.PP +The returned message string will be of the form: +.PP +.Vb 1 +\& XPA$ERROR error\-message (class:name ip:port) +.Ve +.PP +or +.PP +.Vb 1 +\& XPA$MESSAGE message (class:name ip:port) +.Ve +.PP +Note that when there is an error stored in an messages entry, the +corresponding bufs and lens entry may or may not be \s-1NULL\s0 and 0 +(respectively), depending on the particularities of the server. +.PP +The return value will contain the actual number of servers that were +processed. This value thus will hold the number of valid entries in +the bufs, lens, names, and messages arrays, and can be used to loop +through these arrays. In names and/or messages is \s-1NULL\s0, no information is +passed back in that array. +.PP +The bufs, names, and messages arrays should be freed upon completion (if +they are not \s-1NULL\s0); +.PP +The mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R" +The following keywords are recognized: +.PP +.Vb 4 +\& key value default explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& ack true/false true if false, don\*(Aqt wait for ack from server (after callback completes) +\& doxpa true/false true client processes xpa requests +.Ve +.PP +The ack keyword is not very useful, since the server completes the callback +in order to return the data anyway. It is here for completion (and perhaps +for future usefulness). +.PP +Normally, an \s-1XPA\s0 client 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. +.PP +\&\fBExample:\fR +.PP +.Vb 1 +\& #include <xpa.h> +\& +\& #define NXPA 10 +\& int i, got; +\& size_t lens[NXPA]; +\& char *bufs[NXPA]; +\& char *names[NXPA]; +\& char *messages[NXPA]; +\& got = XPAGet(NULL, "ds9", "file", NULL, bufs, lens, names, messages, +\& NXPA); +\& for(i=0; i<got; i++){ +\& if( messages[i] == NULL ){ +\& /* process buf contents */ +\& ProcessImage(bufs[i], ...); +\& free(bufs[i]); +\& } +\& else{ +\& /* error processing */ +\& fprintf(stderr, "ERROR: %s (%s)\en", messages[i], names[i]); +\& } +\& if( names[i] ) +\& free(names[i]); +\& if( messages[i] ) +\& free(messages[i]); +\& } +.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/man3/xpagetfd.3 b/xpa/man/man3/xpagetfd.3 new file mode 100644 index 0000000..1899880 --- /dev/null +++ b/xpa/man/man3/xpagetfd.3 @@ -0,0 +1,235 @@ +.\" 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 "xpagetfd 3" +.TH xpagetfd 3 "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" +\&\fBXPAGetFd: retrieve data from one or more \s-1XPA\s0 servers and write to files\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& int XPAGetFd(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& int *fds, char **names, char **messages, int n); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Retrieve data from one or more \s-1XPA\s0 servers whose class:name identifier +matches the specified +template +and write it to files associated with +one or more standard I/O fds (i.e, handles returned by \fIopen()\fR). +.PP +A +template +of the form \*(L"class1:name1\*(R" is sent to the +\&\s-1XPA\s0 name server, which returns a list of at most \s-1ABS\s0(n) matching \s-1XPA\s0 +servers. A connection is established with each of these servers and +the paramlist string is passed to the server as the data transfer +request is initiated. If an \s-1XPA\s0 struct is passed to the call, then the +persistent connections are updated as described above. Otherwise, +temporary connections are made to the servers (which will be closed +when the call completes). +.PP +The \fIXPAGetFd()\fR routine then retrieves data from the \s-1XPA\s0 servers, +and write these data to the fds associated with one or more fds +(i.e., results from open). Is n is positive, then there will be n fds +and the data from each server will be sent to a separate fd. If n is +negative, then there is only 1 fd and all data is sent to this single +fd. (The latter is how xpaget is implemented.) +.PP +A string containing the class:name and ip:port is stored in the name +array. If a given server returned an error or the server callback +sends a message back to the client, then the message will be stored in +the associated element of the messages array. \s-1NB:\s0 if specified, the +name and messages arrays must be of size n or greater. +.PP +The returned message string will be of the form: +.PP +.Vb 1 +\& XPA$ERROR error\-message (class:name ip:port) +.Ve +.PP +or +.PP +.Vb 1 +\& XPA$MESSAGE message (class:name ip:port) +.Ve +.PP +Note that when there is an error stored in an messages entry, the +corresponding bufs and lens entry may or may not be \s-1NULL\s0 and 0 +(respectively), depending on the particularities of the server. +.PP +The return value will contain the actual number of servers that were +processed. This value thus will hold the number of valid entries in +the bufs, lens, names, and messages arrays, and can be used to loop +through these arrays. In names and/or messages is \s-1NULL\s0, no information is +passed back in that array. +.PP +The mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R" +The following keywords are recognized: +.PP +.Vb 3 +\& key value default explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& ack true/false true if false, don\*(Aqt wait for ack from server (after callback completes) +.Ve +.PP +The ack keyword is not very useful, since the server completes the callback +in order to return the data anyway. It is here for completion (and perhaps +for future usefulness). +.PP +\&\fBExample:\fR +.PP +.Vb 10 +\& #include <xpa.h> +\& #define NXPA 10 +\& int i, got; +\& int fds[NXPA]; +\& char *names[NXPA]; +\& char *messages[NXPA]; +\& for(i=0; i<NXPA; i++) +\& fds[i] = open(...); +\& got = XPAGetFd(NULL, "ds9", "file", NULL, fds, names, messages, NXPA); +\& for(i=0; i<got; i++){ +\& if( messages[i] != NULL ){ +\& /* error processing */ +\& fprintf(stderr, "ERROR: %s (%s)\en", messages[i], names[i]); +\& } +\& if( names[i] ) +\& free(names[i]); +\& if( messages[i] ) +\& free(messages[i]); +\& } +.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/man3/xpainfo.3 b/xpa/man/man3/xpainfo.3 new file mode 100644 index 0000000..4f51a05 --- /dev/null +++ b/xpa/man/man3/xpainfo.3 @@ -0,0 +1,213 @@ +.\" 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 "xpainfo 3" +.TH xpainfo 3 "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" +\&\fBXPAInfo: send short message to one or more \s-1XPA\s0 servers\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& int XPAInfo(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& char **names, char **messages, int n); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Send a short paramlist message to one or more \s-1XPA\s0 servers whose +class:name identifier matches the specified +template. +.PP +A +template +of the form \*(L"class1:name1\*(R" is sent to the +\&\s-1XPA\s0 name server, which returns a list of at most n matching \s-1XPA\s0 +servers. A connection is established with each of these servers and +the paramlist string is passed to the server as the data transfer +request is initiated. If an \s-1XPA\s0 struct is passed to the call, then the +persistent connections are updated as described above. Otherwise, +temporary connections are made to the servers (which will be closed +when the call completes). +.PP +The \fIXPAInfo()\fR routine does not send data from a buf to the \s-1XPA\s0 +servers. Only the paramlist is sent. The semantics of the paramlist +is not formalized, but at a minimum is should tell the server how to +get more information. For example, it might contain the class:name +of the \s-1XPA\s0 access point from which the server (acting as a client) +can obtain more info using XPAGet. +.PP +A string containing the class:name and ip:port of each server is +returned in the name array. If a given server returned an error or +the server callback sends a message back to the client, then the +message will be stored in the associated element of the messages +array. The returned message string will be of the form: +.PP +.Vb 1 +\& XPA$ERROR error\-message (class:name ip:port) +.Ve +.PP +or +.PP +.Vb 1 +\& XPA$MESSAGE message (class:name ip:port) +.Ve +.PP +The return value will contain the actual number of servers that were +processed. This value thus will hold the number of valid entries in +the names and messages arrays, and can be used to loop through these +arrays. In names and/or messages is \s-1NULL\s0, no information is passed back +in that array. +.PP +The following keywords are recognized: +.PP +.Vb 3 +\& key value default explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& ack true/false true if false, don\*(Aqt wait for ack from server +.Ve +.PP +When ack is false, \fIXPAInfo()\fR will not wait for an error return from the \s-1XPA\s0 +server. This means, in effect, that XPAInfo will send its paramlist string +to the \s-1XPA\s0 server and then exit: no information will be sent from the server +to the client. This UDP-like behavior is essential to avoid race +conditions in cases where \s-1XPA\s0 servers are sending info messages to +other servers. If two servers try to send each other an info message +at the same time and then wait for an ack, a race condition will result and +one or both will time out. +.PP +\&\fBExample:\fR +.PP +.Vb 1 +\& (void)XPAInfo(NULL, "IMAGE", "ds9 image", NULL, NULL, NULL, 0); +.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/man3/xpainfonew.3 b/xpa/man/man3/xpainfonew.3 new file mode 100644 index 0000000..bab9739 --- /dev/null +++ b/xpa/man/man3/xpainfonew.3 @@ -0,0 +1,195 @@ +.\" 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 "xpainfonew 3" +.TH xpainfonew 3 "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" +\&\fBXPAInfoNew: define an \s-1XPA\s0 info public access point\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& XPA XPAInfoNew(char *class, char *name, +\& int (*info_callback)(), +\& void *info_data, char *info_mode); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +[\s-1NB:\s0 this is an experimental interface, new to \s-1XPA\s0 2.0, whose value +and best use is evolving.] +.PP +A program can register interest in receiving a short message about a +particular topic from any other process that cares to send such a +message. Neither has to be an \s-1XPA\s0 server. For example, if a user +starts to work with a new image file called new.fits, she might +wish to alert interested programs about this new file by sending a +short message using xpainfo: +.PP +.Vb 1 +\& xpainfo IMAGEFILE /data/new.fits +.Ve +.PP +In this example, each process that has used the \fIXPAInfoNew()\fR call to +register interest in messages associated with the identifier \s-1IMAGEFILE\s0 +will have its \fIinfo_callback()\fR executed with the following calling +sequence: +.PP +.Vb 4 +\& int info_cb(void *info_data, void *call_data, char *paramlist) +\& { +\& XPA xpa = (XPA)call_data; +\& } +.Ve +.PP +The arguments passed to this routine are equivalent to those sent in +the \fIsend_callback()\fR routine. The main difference is that there is no +buf sent to the info callback: this mechanism is meant for short +announcement of messages of interest to many clients. +.PP +The mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R" +The following keywords are recognized: +.PP +.Vb 3 +\& key value default explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& acl true/false true enable access control +.Ve +.PP +Because no buf is passed to this callback, the usual buf-related keywords +are not applicable here. +.PP +The information sent in the parameter list is arbitrary. However, we +envision sending information such as file names or \s-1XPA\s0 access points +from which to collect more data. Note that the xpainfo program and +the \fIXPAInfo()\fR routine that cause the info_callback to execute do not +wait for the callback to complete before returning. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpamacros.3 b/xpa/man/man3/xpamacros.3 new file mode 100644 index 0000000..c9a6ab5 --- /dev/null +++ b/xpa/man/man3/xpamacros.3 @@ -0,0 +1,180 @@ +.\" 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 "xpamacros 3" +.TH xpamacros 3 "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 Server Callback Macros\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& xpa_class, xpa_name, xpa_method, xpa_cmdfd, xpa_datafd, +\& xpa_sendian, xpa_cendian +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Server routines have access to information about the \s-1XPA\s0 being called via +the following macros (each of which takes the xpa handle as an argument): +.PP +.Vb 9 +\& macro explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& xpa_class class of this xpa +\& xpa_name name of this xpa +\& xpa_method method string (inet or local connect info) +\& xpa_cmdfd fd of command socket +\& xpa_datafd fd of data socket +\& xpa_sendian endian\-ness of server ("little" or "big") +\& xpa_cendian endian\-ness of client ("little" or "big" +.Ve +.PP +The argument to these macros is the call_data pointer that is passed +to the server procedure. This pointer should be type case to \s-1XPA\s0 +in the server routine: +.PP +.Vb 1 +\& XPA xpa = (XPA)call_data; +.Ve +.PP +The most important of these macros is \fIxpa_datafd()\fR. A server routine +that sets \*(L"fillbuf=false\*(R" in receive_mode or send_mode can use this +macro to perform I/O directly to/from the client, rather than using +buf. +.PP +The xpa_cendian and xpa_sendian macros can be used together to determine +if the data transferred from the client is byte swapped with respect +to the server. Values for these macros are: \*(L"little\*(R", \*(L"big\*(R", or \*(L"?\*(R". +In order to do a proper conversion, you still need to know the format +of the data (i.e., byte swapping is dependent on the size of the data +element being converted). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpamainloop.3 b/xpa/man/man3/xpamainloop.3 new file mode 100644 index 0000000..ff01099 --- /dev/null +++ b/xpa/man/man3/xpamainloop.3 @@ -0,0 +1,214 @@ +.\" 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 "xpamainloop 3" +.TH xpamainloop 3 "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" +\&\fBXPAMainLoop: optional main loop for \s-1XPA\s0\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& void XPAMainLoop(); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Once \s-1XPA\s0 access points have been defined, a program must enter an +event loop to watch for requests from external programs. This can be +done in a variety of ways, depending on whether the event loop is +processing events other than \s-1XPA\s0 events. In cases where there are no +non-XPA events to be processed, the program can simply call the +\&\fIXPAMainLoop()\fR event loop. This loop is implemented essentially as +follows (error checking is simplified in this example): +.PP +.Vb 8 +\& FD_ZERO(&readfds); +\& while( XPAAddSelect(NULL, &readfds) ){ +\& if( sgot = select(swidth, &readfds, NULL, NULL, NULL) >0 ) +\& XPAProcessSelect(&readfds, 0); +\& else +\& break; +\& FD_ZERO(&readfds); +\& } +.Ve +.PP +The \fIXPAAddSelect()\fR routine sets up the \fIselect()\fR readfds variable so +that \fIselect()\fR will wait for I/O on all the active \s-1XPA\s0 channels. It +returns the number of XPAs that are active; the loop will end when +there are no active XPAs. The standard \fIselect()\fR routine is called to +wait for an external I/O request. Since no timeout struct is passed +in argument 5, the \fIselect()\fR call hangs until there is an external +request. When an external I/O request is made, the \fIXPAProcessSelect()\fR +routine is executed to process the pending requests. In this routine, +the maxreq value determines how many requests will be processed: if +maxreq <=0, then all currently pending requests will be processed. +Otherwise, up to maxreq requests will be processed. (The most usual +values for maxreq is 0 to process all requests.) +.PP +If a program has its own Unix \fIselect()\fR loop, then \s-1XPA\s0 access points can +be added to it by using a variation of the standard XPAMainLoop: +.PP +.Vb 7 +\& XPAAddSelect(xpa, &readfds); +\& [app\-specific ...] +\& if( select(width, &readfds, ...) ){ +\& XPAProcessSelect(&readfds, maxreq); +\& [app\-specific ...] +\& FD_ZERO(&readfds); +\& } +.Ve +.PP +\&\fIXPAAddSelect()\fR is called before \fIselect()\fR to add the access points. +If the first argument is \s-1NULL\s0, then all active \s-1XPA\s0 access points +are added. Otherwise only the specified access point is added. +After \fIselect()\fR is called, the \fIXPAProcessSelect()\fR routine can be called +to process \s-1XPA\s0 requests. Once again, the maxreq value determines how +many requests will be processed: if maxreq <=0, then all currently +pending requests will be processed. Otherwise, up to maxreq requests +will be processed. +.PP +\&\s-1XPA\s0 access points can be added to +Xt event loops (using \fIXtAppMainLoop()\fR) +and +Tcl/Tk event loops (using vwait and the Tk loop). +When using \s-1XPA\s0 with these event loops, you only need to call: +.PP +int XPAXtAddInput(XtAppContext app, \s-1XPA\s0 xpa) +.PP +or +.PP +.Vb 1 +\& int XPATclAddInput(XPA xpa) +.Ve +.PP +respectively before entering the loop. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpanew.3 b/xpa/man/man3/xpanew.3 new file mode 100644 index 0000000..f4f72b6 --- /dev/null +++ b/xpa/man/man3/xpanew.3 @@ -0,0 +1,344 @@ +.\" 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 "xpanew 3" +.TH xpanew 3 "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" +\&\fBXPANew: create a new \s-1XPA\s0 access point\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& XPA XPANew(char *class, char *name, char *help, +\& int (*send_callback)(), +\& void *send_data, char *send_mode, +\& int (*rec_callback)(), +\& void *rec_data, char *rec_mode); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Create a new \s-1XPA\s0 public access point with the class:name +identifier template +and enter this access point into the \s-1XPA\s0 name server, so that it +can be accessed by external processes. \fIXPANew()\fR returns an \s-1XPA\s0 struct. +Note that the length of the class and name designations must be less +than or equal to 1024 characters each. +.PP +The \s-1XPA\s0 name server daemon, xpans, will be started automatically if it +is not running already (assuming it can be found in the path). The +program's ip address and listening port are specified by the +environment variable \s-1XPA_NSINET\s0, which takes the form :. If +no such environment variable exists, then xpans is started on the +current machine listening on port 14285. It also uses 14286 as a +known port for its public access point (so that routines do not have +to go to the name server to find the name server ip and port!) +As of \s-1XPA\s0 2.1.1, version information is exchanged between the xpans +process and the new access point. If the access point uses an \s-1XPA\s0 +major/minor version newer than xpans, a warning is issued by both processes, +since mixing of new servers and old xpa programs (xpaset, xpaget, +xpans, etc.) is not likely to work. You can turn off the warning +message by setting the \s-1XPA_VERSIONCHECK\s0 environment variable to \*(L"false\*(R". +.PP +The help string is meant to be returned by a request from xpaget: +.PP +.Vb 1 +\& xpaget class:name \-help +.Ve +.PP +A send_callback and/or a receive_callback can be specified; at +least one of them must be specified. +.PP +A send_callback can be specified that will be executed in response to +an external request from the xpaget program, the \fIXPAGet()\fR routine, or +\&\fIXPAGetFd()\fR routine. This callback is used to send data to the +requesting client. +.PP +The calling sequence for \fIsend_callback()\fR is: +.PP +.Vb 7 +\& int send_callback(void *send_data, void *call_data, +\& char *paramlist, char **buf, size_t *len) +\& { +\& XPA xpa = (XPA)call_data; +\& ... +\& return(stat); +\& } +.Ve +.PP +The send_mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R" +The following keywords are recognized: +.PP +.Vb 4 +\& key value default explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& acl true/false true enable access control +\& freebuf true/false true free buf after callback completes +.Ve +.PP +The call_data should be recast to the \s-1XPA\s0 struct as shown. In +addition, client-specific data can be passed to the callback in +send_data. +.PP +The paramlist will be supplied by the client as qualifying parameters +for the callback. There are two ways in which the \fIsend_callback()\fR +routine can send data back to the client: +.PP +1. The \fIsend_callback()\fR routine can fill in a buffer and pass back a +pointer to this buffer. An integer len also is returned to specify the +number of bytes of data in buf. \s-1XPA\s0 will send this buffer to the +client after the callback is complete. +.PP +2. The send_callback can send data directly to the client by writing +to the fd pointed by the macro: +.PP +.Vb 1 +\& xpa_datafd(xpa) +.Ve +.PP +Note that this fd is of the kind returned by \fIsocket()\fR or \fIopen()\fR. +.PP +If a buf has been allocated by a standard malloc routine, filled, and +returned to \s-1XPA\s0, then freebuf generally is set so that the buffer will +be freed automatically when the callback is completed and data has +been sent to the client. If a static buf is returned, freebuf should +be set to false to avoid a system error when freeing static storage. +Note that default value for freebuf implies that the callback will +allocate a buffer rather than use static storage. +.PP +On the other hand, if buf is dynamically allocated using a method +other than a standard malloc/calloc/realloc routine (e.g. using Perl's +memory allocation and garbage collection scheme), then it is necessary +to tell \s-1XPA\s0 how to free the allocated buffer. To do this, use the +\&\fIXPASetFree()\fR routine within your callback: +.PP +.Vb 1 +\& void XPASetFree(XPA xpa, void (*myfree)(void *), void *myfree_ptr); +.Ve +.PP +The first argument is the usual \s-1XPA\s0 handle. The second argument is the +special routine to call to free your allocated memory. The third +argument is an optional pointer. If not \s-1NULL\s0, the specified free +routine is called with that pointer as its sole argument. If \s-1NULL\s0, the +free routine is called with the standard buf pointer as its sole +argument. This is useful in cases where there is a mapping between the +buffer pointer and the actual allocated memory location, and the +special routine is expecting to be passed the former. +.PP +If, while the callback performs its processing, an error occurs that +should be communicated to the client, then the routine XPAError should be +called: +.PP +.Vb 1 +\& XPAError(XPA xpa, char *s); +.Ve +.PP +where s is an arbitrary error message. The returned error message +string will be of the form: +.PP +.Vb 1 +\& XPA$ERROR [error] (class:name ip:port) +.Ve +.PP +If the callback wants to send a specific acknowledgment message back +to the client, the routine XPAMessage can be called: +.PP +.Vb 1 +\& XPAMessage(XPA xpa, char *s); +.Ve +.PP +where s is an arbitrary error message. The returned error message +string will be of the form: +.PP +.Vb 1 +\& XPA$MESSAGE [message] (class:name ip:port) +.Ve +.PP +Otherwise, a standard acknowledgment is sent back to the client +after the callback is completed. +.PP +The callback routine should return 0 if no error occurs, or \-1 to +signal an error. +.PP +A receive_callback can be specified that will be executed in response +to an external request from the xpaset program, or the XPASet (or +\&\fIXPASetFd()\fR) routine. This callback is used to process data received +from an external process. +.PP +The calling sequence for receive_callback is: +.PP +.Vb 7 +\& int receive_callback(void *receive_data, void *call_data, +\& char *paramlist, char *buf, size_t len) +\& { +\& XPA xpa = (XPA)call_data; +\& ... +\& return(stat); +\& } +.Ve +.PP +The mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R" +The following keywords are recognized: +.PP +.Vb 6 +\& key value default explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& acl true/false true enable access control +\& buf true/false true server expects data bytes from client +\& fillbuf true/false true read data into buf before executing callback +\& freebuf true/false true free buf after callback completes +.Ve +.PP +The call_data should be recast to the \s-1XPA\s0 struct as shown. In +addition, client-specific data can be passed to the callback in +receive_data. +.PP +The paramlist will be supplied by the client. In addition, if the +receive_mode keywords buf and fillbuf are true, then on entry into the +\&\fIreceive_callback()\fR routine, buf will contain the data sent by the +client. If buf is true but fillbuf is false, it becomes the callback's +responsibility to retrieve the data from the client, using the data fd +pointed to by the macro xpa_datafd(xpa). If freebuf is true, then buf +will be freed when the callback is complete. +.PP +If, while the callback is performing its processing, an error occurs +that should be communicated to the client, then the routine XPAError +can be called: +.PP +.Vb 1 +\& XPAError(XPA xpa, char *s); +.Ve +.PP +where s is an arbitrary error message. +.PP +The callback routine should return 0 if no error occurs, or \-1 to +signal an error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpanslookup.3 b/xpa/man/man3/xpanslookup.3 new file mode 100644 index 0000000..8725e3e --- /dev/null +++ b/xpa/man/man3/xpanslookup.3 @@ -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 "xpanslookup 3" +.TH xpanslookup 3 "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" +\&\fBXPANSLookup: lookup registered \s-1XPA\s0 access points\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& int XPANSLookup(XPA xpa, +\& char *template, char type, +\& char ***classes, char ***names, +\& char ***methods, char ***infos) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1XPA\s0 routines act on a class:name identifier in such a way +that all access points that match the identifier are processed. It is +sometimes desirable to choose specific access points from the +candidates that match the +template. In order to do this, the +XPANSLookup routine can be called to return a list of matches, so that +specific class:name instances can then be fed to \fIXPAGet()\fR, \fIXPASet()\fR, etc. +.PP +.Vb 4 +\& The first argument is an optional XPA struct. If non\-NULL, the +\&existing name server connection associated with the specified xpa is +\&used to query the xpans name server for matching templates. Otherwise, +\&a new (temporary) connection is established with the name server. +.Ve +.PP +The second argument to XPANSLookup is the class:name +template +to match. +.PP +The third argument for \fIXPANSLookup()\fR is the type of access and can be +any combination of: +.PP +.Vb 5 +\& type explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& g xpaget calls can be made on this access point +\& s xpaset calls can be made on this access point +\& i xpainfo calls can be made on this access point +.Ve +.PP +The call typically specifies only one of these at a time. +.PP +The final arguments are pointers to arrays that will be filled +in and returned by the name server. The name server will allocate and +return arrays filled with the classes, names, and methods of all \s-1XPA\s0 +access points that match the template +and have the specified type. Also returned are info strings, which +generally are used internally by the client routines. These can be +ignored (but the strings must be freed). The function returns the +number of matches. The returned value can be used to loop through the +matches: +.PP +\&\fBExample:\fR +.PP +.Vb 1 +\& #include <xpa.h> +\& +\& char **classes; +\& char **names; +\& char **methods; +\& char **infos; +\& int i, n; +\& n = XPANSLookup(NULL, "foo*", "g", &classes, &names, &methods, &infos); +\& for(i=0; i<n; i++){ +\& [more specific checks on possibilities ...] +\& [perhaps a call to XPAGet for those that pass, etc. ...] +\& /* don\*(Aqt forget to free alloc\*(Aqed strings when done */ +\& free(classes[i]); +\& free(names[i]); +\& free(methods[i]); +\& free(infos[i]); +\& } +\& /* free up arrays alloc\*(Aqed by names server */ +\& if( n > 0 ){ +\& free(classes); +\& free(names); +\& free(methods); +\& free(infos); +\& } +.Ve +.PP +The specified +template +also can be a host:port specification, for example: +.PP +.Vb 1 +\& myhost:12345 +.Ve +.PP +In this case, no connection is made to the name server. Instead, the +call will return one entry such that the ip array contains the ip for +the specified host and the port array contains the port. The class +and name entries are set to the character \*(L"?\*(R", since the class and +name of the access point are not known. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpaopen.3 b/xpa/man/man3/xpaopen.3 new file mode 100644 index 0000000..c62af06 --- /dev/null +++ b/xpa/man/man3/xpaopen.3 @@ -0,0 +1,172 @@ +.\" 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 "xpaopen 3" +.TH xpaopen 3 "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" +\&\fBXPAOpen: allocate a persistent client handle\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& XPA XPAOpen(char *mode); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fIXPAOpen()\fR allocates a persistent \s-1XPA\s0 struct that can be used with +calls to \fIXPAGet()\fR, \fIXPASet()\fR, \fIXPAInfo()\fR, \fIXPAGetFd()\fR, and +\&\fIXPASetFd()\fR. Persistence means that a connection to an \s-1XPA\s0 server is +not closed when one of the above calls is completed but will be +re-used on successive calls. Using \fIXPAOpen()\fR therefore saves the time +it takes to connect to a server, which could be significant with slow +connections or if there will be a large number of exchanges with a +given access point. The mode argument currently is ignored (\*(L"reserved +for future use\*(R"). +.PP +An \s-1XPA\s0 struct is returned if \fIXPAOpen()\fR was successful; otherwise \s-1NULL\s0 +is returned. This returned struct can be passed as the first argument +to \fIXPAGet()\fR, etc. Those calls will update the list of active \s-1XPA\s0 +connections. Already connected servers (from a previous call) are +left connected and new servers also will be connected. Old servers +(from a previous call) that are no longer needed are disconnected. +The connected servers will remain connected when the next call to +\&\fIXPAGet()\fR is made and connections are once again updated. +.PP +\&\fBExample:\fR +.PP +.Vb 1 +\& #include <xpa.h> +\& +\& XPA xpa; +\& xpa = XPAOpen(NULL); +.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/man3/xpapoll.3 b/xpa/man/man3/xpapoll.3 new file mode 100644 index 0000000..61d3c28 --- /dev/null +++ b/xpa/man/man3/xpapoll.3 @@ -0,0 +1,163 @@ +.\" 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 "xpapoll 3" +.TH xpapoll 3 "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" +\&\fBXPAPoll: execute existing \s-1XPA\s0 requests\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& int XPAPoll(int msec, int maxreq); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +It is sometimes desirable to implement a polling loop, i.e., where one +checks for and processes \s-1XPA\s0 requests without blocking. For this +situation, use the \fIXPAPoll()\fR routine: +.PP +.Vb 1 +\& XPAPoll(int msec, int maxreq); +.Ve +.PP +The \fIXPAPoll()\fR routine will perform \fIXPAAddSelect()\fR and \fIselect()\fR, but with a +timeout specified in millisecs by the msec argument. If one or more +\&\s-1XPA\s0 requests are made before the timeout expires, the \fIXPAProcessSelect()\fR +routine is called to process those requests. The maxreq value determines +how many requests will be processed: if maxreq < 0, then no events are +processed, but instead, the return value indicates the number of events +that are pending. If maxreq == 0, then all currently pending requests +will be processed. Otherwise, up to maxreq requests will be processed. +(The most usual values for maxreq are 0 to process all requests and 1 +to process one request). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xparace.3 b/xpa/man/man3/xparace.3 new file mode 100644 index 0000000..6100196 --- /dev/null +++ b/xpa/man/man3/xparace.3 @@ -0,0 +1,191 @@ +.\" 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 "xparace 3" +.TH xparace 3 "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 Race Conditions\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +Potential \s-1XPA\s0 race conditions and how to avoid them. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Currently, there is only one known circumstance in which \s-1XPA\s0 can get +(temporarily) deadlocked in a race condition: if two or more \s-1XPA\s0 +servers send messages to one another using an \s-1XPA\s0 client routine such +as \fIXPASet()\fR, they can deadlock while each waits for the other server +to respond. (This can happen if the servers call \fIXPAPoll()\fR with a +time limit, and send messages in between the polling call.) The +reason this happens is that both client routines send a string to the +other server to establish the handshake and then wait for the server +response. Since each client is waiting for a response, neither is able +to enter its event-handling loop and respond to the other's +request. This deadlock will continue until one of the timeout periods +expire, at which point an error condition will be triggered and the +timed-out server will return to its event loop. +.PP +Starting with version 2.1.6, this rare race condition can be +avoided by setting the \s-1XPA_IOCALLSXPA\s0 environment variable for servers +that will make client calls. 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. It also means that a server callback +routine can handle incoming \s-1XPA\s0 messages if it makes its own \s-1XPA\s0 call. +The semi-public routine oldvalue=XPAIOCallsXPA(newvalue) can be used +to turn this behavior off and on temporarily. Passing a 0 will turn +off \s-1IO\s0 processing, 1 will turn it back on. The old value is returned +by the call. +.PP +By default, the \s-1XPA_IOCALLSXPA\s0 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. +.PP +Aside from setting \s-1XPA_IOCALLSXPA\s0, the simplest way to avoid this race +condition is to multi-process: when you want to send a client message, +simply start a separate process to call the client routine, so that +the server is not stopped. It probably is fastest and easiest to use +\&\fIfork()\fR and then have the child call the client routine and exit. But +you also can use either the \fIsystem()\fR or \fIpopen()\fR routine to start one +of the command line programs and do the same thing. Alternatively, you +can use \s-1XPA\s0's internal \fIlaunch()\fR routine instead of \fIsystem()\fR. Based on +\&\fIfork()\fR and \fIexec()\fR, this routine is more secure than \fIsystem()\fR because +it does not call /bin/sh. +.PP +Starting with version 2.1.5, you also can send an \fIXPAInfo()\fR message with +the mode string \*(L"ack=false\*(R". This will cause the client to send a message +to the server and then exit without waiting for any return message from +the server. This UDP-like behavior will avoid the server deadlock when +sending short XPAInfo messages. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpaserver.3 b/xpa/man/man3/xpaserver.3 new file mode 100644 index 0000000..a0803aa --- /dev/null +++ b/xpa/man/man3/xpaserver.3 @@ -0,0 +1,205 @@ +.\" 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 "xpaserver 3" +.TH xpaserver 3 "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" +\&\fBXPAServer: The \s-1XPA\s0 Server-side Programming Interface\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +A description of the \s-1XPA\s0 server-side programming interface. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBIntroduction to \s-1XPA\s0 Server Programming\fR +.PP +Creating an \s-1XPA\s0 server is easy: you generally only need to call the +\&\fIXPANew()\fR subroutine to define a named \s-1XPA\s0 access point and set up the +send and receive callback routines. You then enter an event loop such +as \fIXPAMainLoop()\fR to field \s-1XPA\s0 requests. +.PP +.Vb 1 +\& #include <xpa.h> +\& +\& XPA XPANew(char *class, char *name, char *help, +\& int (*send_callback)(), void *send_data, char *send_mode, +\& int (*rec_callback)(), void *rec_data, char *rec_mode); +\& +\& XPA XPACmdNew(char *class, char *name); +\& +\& XPACmd XPACmdAdd(XPA xpa, +\& char *name, char *help, +\& int (*send_callback)(), void *send_data, char *send_mode, +\& int (*rec_callback)(), void *rec_data, char *rec_mode); +\& +\& void XPACmdDel(XPA xpa, XPACmd cmd); +\& +\& XPA XPAInfoNew(char *class, char *name, +\& int (*info_callback)(), void *info_data, char *info_mode); +\& +\& int XPAFree(XPA xpa); +\& +\& void XPAMainLoop(void); +\& +\& int XPAPoll(int msec, int maxreq); +\& +\& void XPAAtExit(void); +\& +\& void XPACleanup(void); +.Ve +.PP +\&\fBIntroduction\fR +.PP +To use the \s-1XPA\s0 application programming interface, a software developer +generally will include the xpa.h definitions file: +.PP +.Vb 1 +\& #include <xpa.h> +.Ve +.PP +in the software module that defines or accesses an \s-1XPA\s0 access point, and +then will link against the libxpa.a library: +.PP +.Vb 1 +\& gcc \-o foo foo.c libxpa.a +.Ve +.PP +\&\s-1XPA\s0 has been compiled using both C and \*(C+ compilers. +.PP +A server program generally defines an \s-1XPA\s0 access point by calling the +\&\fIXPANew()\fR routine and specifies \*(L"send\*(R" and/or \*(L"receive\*(R" callback +procedures to be executed by the program when an external process +either sends data or commands to this access point or requests data or +information from this access point. A program also can define several +sub-commands for a single access point by calling \fIXPACmdNew()\fR and +\&\fIXPACmdAdd()\fR instead. 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). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages diff --git a/xpa/man/man3/xpaset.3 b/xpa/man/man3/xpaset.3 new file mode 100644 index 0000000..d9dd7c0 --- /dev/null +++ b/xpa/man/man3/xpaset.3 @@ -0,0 +1,236 @@ +.\" 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 "xpaset 3" +.TH xpaset 3 "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" +\&\fBXPASet: send data to one or more \s-1XPA\s0 servers\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& int XPASet(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& char *buf, size_t len, char **names, char **messages, +\& int n); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Send data to one or more \s-1XPA\s0 servers whose class:name identifier +matches the specified template. +.PP +A +template +of the form \*(L"class1:name1\*(R" is sent to the +\&\s-1XPA\s0 name server, which returns a list of at most n matching \s-1XPA\s0 +servers. A connection is established with each of these servers and +the paramlist string is passed to the server as the data transfer +request is initiated. If an \s-1XPA\s0 struct is passed to the call, the +persistent connections are updated as described above. Otherwise, +temporary connections are made to the servers (which will be closed +when the call completes). +.PP +The \fIXPASet()\fR routine transfers data from buf to the \s-1XPA\s0 servers. +The length of buf (in bytes) should be placed in the len variable. +.PP +A string containing the class:name and ip:port of each of these server +is returned in the name array. If a given server returned an error or +the server callback sends a message back to the client, then the +message will be stored in the associated element of the messages +array. \s-1NB:\s0 if specified, the name and messages arrays must be of size +n or greater. +.PP +The returned message string will be of the form: +.PP +.Vb 1 +\& XPA$ERROR [error] (class:name ip:port) +.Ve +.PP +or +.PP +.Vb 1 +\& XPA$MESSAGE [message] (class:name ip:port) +.Ve +.PP +The return value will contain the actual number of servers that were +processed. This value thus will hold the number of valid entries in +the names and messages arrays, and can be used to loop through these +arrays. In names and/or messages is \s-1NULL\s0, no information is passed back +in that particular array. +.PP +The mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R" +The following keywords are recognized: +.PP +.Vb 5 +\& key value default explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& ack true/false true if false, don\*(Aqt wait for ack from server (after callback completes) +\& verify true/false false send buf from XPASet[Fd] to stdout +\& doxpa true/false true client processes xpa requests +.Ve +.PP +The ack keyword is useful in cases where one does not want to wait for +the server to complete, e.g. if a lot of processing needs to be done +by the server on the passed data or when the success of the server +operation is not relevant to the client. +.PP +Normally, an \s-1XPA\s0 client 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. +.PP +\&\fBExample:\fR +.PP +.Vb 1 +\& #include <xpa.h> +\& +\& #define NXPA 10 +\& int i, got; +\& size_t len; +\& char *buf; +\& char *names[NXPA]; +\& char *messages[NXPA]; +\& ... +\& [fill buf with data and set len to the length, in bytes, of the data] +\& ... +\& /* send data to all access points */ +\& got = XPASet(NULL, "ds9", "fits", NULL, buf, len, names, messages, NXPA); +\& /* error processing */ +\& for(i=0; i<got; i++){ +\& if( messages[i] ){ +\& fprintf(stderr, "ERROR: %s (%s)\en", messages[i], names[i]); +\& } +\& if( names[i] ) free(names[i]); +\& if( messages[i] ) free(messages[i]); +\& } +.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/man3/xpasetfd.3 b/xpa/man/man3/xpasetfd.3 new file mode 100644 index 0000000..5017a38 --- /dev/null +++ b/xpa/man/man3/xpasetfd.3 @@ -0,0 +1,214 @@ +.\" 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 "xpasetfd 3" +.TH xpasetfd 3 "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" +\&\fBXPASetFd: send data from stdin to one or more \s-1XPA\s0 servers\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <xpa.h> +\& +\& int XPASetFd(XPA xpa, +\& char *template, char *paramlist, char *mode, +\& int fd, char **names, char **messages, int n) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Read data from a standard I/O fd and send it to one or more \s-1XPA\s0 +servers whose class:name identifier matches the specified +template. +.PP +A +template +of the form \*(L"class1:name1\*(R" is sent to the +\&\s-1XPA\s0 name server, which returns a list of at most n matching \s-1XPA\s0 +servers. A connection is established with each of these servers and +the paramlist string is passed to the server as the data transfer +request is initiated. If an \s-1XPA\s0 struct is passed to the call, then the +persistent connections are updated as described above. Otherwise, +temporary connections are made to the servers (which will be closed +when the call completes). +.PP +The \fIXPASetFd()\fR routine then reads bytes from the specified fd +until \s-1EOF\s0 and sends these bytes to the \s-1XPA\s0 servers. +The final parameter n specifies the maximum number of servers to contact. +A string containing the class:name and ip:port of each server is returned in +the name array. If a given server returned an error, then the error +message will be stored in the associated element of the messages array. +\&\s-1NB:\s0 if specified, the name and messages arrays must be of size n or greater. +.PP +The return value will contain the actual number of servers that were +processed. This value thus will hold the number of valid entries in +the names and messages arrays, and can be used to loop through these +arrays. In names and/or messages is \s-1NULL\s0, no information is passed back +in that array. +.PP +The mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R" +The following keywords are recognized: +.PP +.Vb 4 +\& key value default explanation +\& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- +\& ack true/false true if false, don\*(Aqt wait for ack from server (after callback completes) +\& verify true/false false send buf from XPASet[Fd] to stdout +.Ve +.PP +The ack keyword is useful in cases where one does not want to wait for +the server to complete, e.g. is a lot of processing needs to be done +on the passed data or when the success of the server operation is not +relevant to the client. +.PP +\&\fBExample:\fR +.PP +.Vb 1 +\& #include <xpa.h> +\& +\& #define NXPA 10 +\& int i, got; +\& int fd; +\& char *names[NXPA]; +\& char *messages[NXPA]; +\& fd = open(...); +\& got = XPASetFd(NULL, "ds9", "fits", NULL, fd, names, messages, NXPA); +\& for(i=0; i<got; i++){ +\& if( messages[i] != NULL ){ +\& /* error processing */ +\& fprintf(stderr, "ERROR: %s (%s)\en", messages[i], names[i]); +\& } +\& if( names[i] ) +\& free(names[i]); +\& if( messages[i] ) +\& free(messages[i]); +\& } +.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/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 |