Debian Codegraph @

cextern/xpa/man/man3/xpaaccess.3

raw
1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD. Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 . de IX
53 . tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 . nr % 0
56 . rr F
57 .\}
58 .el \{\
59 . de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
66 .if n \{\
67 . ds #H 0
68 . ds #V .8m
69 . ds #F .3m
70 . ds #[ \f1
71 . ds #] \fP
72 .\}
73 .if t \{\
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 . ds #V .6m
76 . ds #F 0
77 . ds #[ \&
78 . ds #] \&
79 .\}
80 . \" simple accents for nroff and troff
81 .if n \{\
82 . ds ' \&
83 . ds ` \&
84 . ds ^ \&
85 . ds , \&
86 . ds ~ ~
87 . ds /
88 .\}
89 .if t \{\
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 . ds : e
114 . ds 8 ss
115 . ds o a
116 . ds d- d\h'-1'\(ga
117 . ds D- D\h'-1'\(hy
118 . ds th \o'bp'
119 . ds Th \o'LP'
120 . ds ae ae
121 . ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "xpaaccess 3"
127 .TH xpaaccess 3 "July 23, 2013" "version 2.1.15" "SAORD Documentation"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 XPAAccess: return XPA access points matching
134 template (XPA 2.1 and above)
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 .Vb 1
138 \& #include <xpa.h>
139 \&
140 \& int XPAAccess(XPA xpa,
141 \& char *template, char *paramlist, char *mode,
142 \& char **names, char **messages, int n);
143 .Ve
144 .SH "DESCRIPTION"
145 .IX Header "DESCRIPTION"
146 The XPAAccess routine returns the public access points that match the
147 specified second argument template and
148 have the specified access type.
149 .PP
150 A
151 template
152 of the form \*(L"class1:name1\*(R" is sent to the
153 \&\s-1XPA\s0 name server, which returns a list of at most n matching \s-1XPA\s0
154 servers. A connection is established with each of these servers and
155 the paramlist string is passed to the server as the data transfer
156 request is initiated. If an \s-1XPA\s0 struct is passed to the call, then the
157 persistent connections are updated as described above. Otherwise,
158 temporary connections are made to the servers (which will be closed
159 when the call completes).
160 .PP
161 The \fIXPAAccess()\fR routine retrieves names from at most n \s-1XPA\s0 servers
162 that match the specified template and that were checked for access
163 using the specified mode. The return string contains both the
164 class:name and ip:port. If a given server returned an error or the
165 server callback sends a message back to the client, then the message
166 will be stored in the associated element of the messages array.
167 \&\s-1NB:\s0 if specified, the name and messages arrays must be of size n or greater.
168 .PP
169 The returned message string will be of the form:
170 .PP
171 .Vb 1
172 \& XPA$ERROR error\-message (class:name ip:port)
173 .Ve
174 .PP
175 Note that names of matching registered access points are always
176 returned but may not be valid; it is not sufficient to assume that the
177 returned number of access points is the number of valid access points.
178 Rather, it is essential to check the messages array for error
179 messages. Any string in the messages array is an error message and
180 indicated that the associated access point is not available.
181 .PP
182 For example, assume that a server registers a number of access points
183 but delays entering its event loop. If a call to \fIXPAAccess()\fR is made
184 before the event loop is entered, the call will timeout (after waiting
185 for the long timeout period) and return an error of the form:
186 .PP
187 .Vb 1
188 \& XPA$ERROR: timeout waiting for server authentication (XPA:xpa1)
189 .Ve
190 .PP
191 The error means that the \s-1XPA\s0 access point has been registered but is
192 not yet available (because events are not being processed). When the
193 server finally enters its event loop, subsequent calls to \fIXPAAccess()\fR
194 will return successfully.
195 .PP
196 \&\s-1NB:\s0 This routine only works with \s-1XPA\s0 servers built with \s-1XPA\s0 2.1.x and later.
197 Servers with older versions of \s-1XPA\s0 will return the error message:
198 .PP
199 .Vb 1
200 \& XPA$ERROR invalid xpa command in initialization string
201 .Ve
202 .PP
203 If you get this error message, then the old server actually is ready
204 for access, since it got to the point of fielding the query! The
205 xpaaccess program, for example, ignores this message in order to work
206 properly with older servers.
207 .PP
208 The third argument for \fIXPAAccess()\fR is the type of access and can be
209 any combination of:
210 .PP
211 .Vb 5
212 \& type explanation
213 \& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
214 \& g xpaget calls can be made on this access point
215 \& s xpaset calls can be made on this access point
216 \& i xpainfo calls can be made on this access point
217 .Ve
218 .PP
219 The mode string argument is of the form: \*(L"key1=value1,key2=value2,...\*(R"
220 The following keywords are recognized:
221 .PP
222 .Vb 3
223 \& key value default explanation
224 \& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
225 \& ack true/false true if false, don\*(Aqt wait for ack from server (after callback completes)
226 .Ve
227 .PP
228 The ack keyword is not very useful, since the server completes the callback
229 in order to return the data anyway. It is here for completion (and perhaps
230 for future usefulness).
231 .SH "SEE ALSO"
232 .IX Header "SEE ALSO"
233 See xpa(n) for a list of \s-1XPA\s0 help pages