diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2017-10-26 16:45:12 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2017-10-26 16:45:12 (GMT) |
commit | dd1df8d8538f275b17e0d9d50dca19f4d44595fd (patch) | |
tree | 624bc07023b33668147eaa9097279c6fc92b4e48 /xpa/man/man3 | |
parent | 79d64f400391ce81b4eda73977cb40099256b348 (diff) | |
parent | 6054f36bb658916bd231b9002efb94444e2871c8 (diff) | |
download | blt-dd1df8d8538f275b17e0d9d50dca19f4d44595fd.zip blt-dd1df8d8538f275b17e0d9d50dca19f4d44595fd.tar.gz blt-dd1df8d8538f275b17e0d9d50dca19f4d44595fd.tar.bz2 |
Merge commit '6054f36bb658916bd231b9002efb94444e2871c8' as 'xpa'
Diffstat (limited to 'xpa/man/man3')
-rw-r--r-- | xpa/man/man3/xpaaccess.3 | 233 | ||||
-rw-r--r-- | xpa/man/man3/xpaatexit.3 | 149 | ||||
-rw-r--r-- | xpa/man/man3/xpacleanup.3 | 151 | ||||
-rw-r--r-- | xpa/man/man3/xpaclient.3 | 206 | ||||
-rw-r--r-- | xpa/man/man3/xpaclose.3 | 157 | ||||
-rw-r--r-- | xpa/man/man3/xpacmdadd.3 | 174 | ||||
-rw-r--r-- | xpa/man/man3/xpacmddel.3 | 147 | ||||
-rw-r--r-- | xpa/man/man3/xpacmdnew.3 | 196 | ||||
-rw-r--r-- | xpa/man/man3/xpafree.3 | 153 | ||||
-rw-r--r-- | xpa/man/man3/xpaget.3 | 244 | ||||
-rw-r--r-- | xpa/man/man3/xpagetfd.3 | 235 | ||||
-rw-r--r-- | xpa/man/man3/xpainfo.3 | 213 | ||||
-rw-r--r-- | xpa/man/man3/xpainfonew.3 | 195 | ||||
-rw-r--r-- | xpa/man/man3/xpamacros.3 | 180 | ||||
-rw-r--r-- | xpa/man/man3/xpamainloop.3 | 214 | ||||
-rw-r--r-- | xpa/man/man3/xpanew.3 | 344 | ||||
-rw-r--r-- | xpa/man/man3/xpanslookup.3 | 232 | ||||
-rw-r--r-- | xpa/man/man3/xpaopen.3 | 172 | ||||
-rw-r--r-- | xpa/man/man3/xpapoll.3 | 163 | ||||
-rw-r--r-- | xpa/man/man3/xparace.3 | 191 | ||||
-rw-r--r-- | xpa/man/man3/xpaserver.3 | 205 | ||||
-rw-r--r-- | xpa/man/man3/xpaset.3 | 236 | ||||
-rw-r--r-- | xpa/man/man3/xpasetfd.3 | 214 |
23 files changed, 4604 insertions, 0 deletions
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 |