Debian Codegraph @

cextern/xpa/man/man3/xpaget.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 "xpaget 3"
127 .TH xpaget 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 \&\fBXPAGet: retrieve data from one or more \s-1XPA\s0 servers\fR
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 .Vb 1
137 \& #include <xpa.h>
138 \&
139 \& int XPAGet(XPA xpa,
140 \& char *template, char *paramlist, char *mode,
141 \& char **bufs, size_t *lens, char **names, char **messages,
142 \& int n);
143 .Ve
144 .SH "DESCRIPTION"
145 .IX Header "DESCRIPTION"
146 Retrieve data from one or more \s-1XPA\s0 servers whose class:name identifier
147 matches the specified template.
148 .PP
149 A
150 template
151 of the form \*(L"class1:name1\*(R" is sent to the
152 \&\s-1XPA\s0 name server, which returns a list of at most n matching \s-1XPA\s0
153 servers. A connection is established with each of these servers and
154 the paramlist string is passed to the server as the data transfer
155 request is initiated. If an \s-1XPA\s0 struct is passed to the call, then the
156 persistent connections are updated as described above. Otherwise,
157 temporary connections are made to the servers (which will be closed
158 when the call completes).
159 .PP
160 The \fIXPAGet()\fR routine then retrieves data from at most n \s-1XPA\s0 servers,
161 places these data into n allocated buffers and places the buffer
162 pointers in the bufs array. The length of each buffer is stored in the
163 lens array. A string containing the class:name and ip:port is stored
164 in the name array. If a given server returned an error or the server
165 callback sends a message back to the client, then the message will be
166 stored in the associated element of the messages array. \s-1NB:\s0 if
167 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 or
176 .PP
177 .Vb 1
178 \& XPA$MESSAGE message (class:name ip:port)
179 .Ve
180 .PP
181 Note that when there is an error stored in an messages entry, the
182 corresponding bufs and lens entry may or may not be \s-1NULL\s0 and 0
183 (respectively), depending on the particularities of the server.
184 .PP
185 The return value will contain the actual number of servers that were
186 processed. This value thus will hold the number of valid entries in
187 the bufs, lens, names, and messages arrays, and can be used to loop
188 through these arrays. In names and/or messages is \s-1NULL\s0, no information is
189 passed back in that array.
190 .PP
191 The bufs, names, and messages arrays should be freed upon completion (if
192 they are not \s-1NULL\s0);
193 .PP
194 The mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R"
195 The following keywords are recognized:
196 .PP
197 .Vb 4
198 \& key value default explanation
199 \& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
200 \& ack true/false true if false, don\*(Aqt wait for ack from server (after callback completes)
201 \& doxpa true/false true client processes xpa requests
202 .Ve
203 .PP
204 The ack keyword is not very useful, since the server completes the callback
205 in order to return the data anyway. It is here for completion (and perhaps
206 for future usefulness).
207 .PP
208 Normally, an \s-1XPA\s0 client will process incoming \s-1XPA\s0 server requests
209 while awaiting the completion of the client request. Setting this
210 variable to \*(L"false\*(R" will prevent \s-1XPA\s0 server requests from being
211 processed by the client.
212 .PP
213 \&\fBExample:\fR
214 .PP
215 .Vb 1
216 \& #include <xpa.h>
217 \&
218 \& #define NXPA 10
219 \& int i, got;
220 \& size_t lens[NXPA];
221 \& char *bufs[NXPA];
222 \& char *names[NXPA];
223 \& char *messages[NXPA];
224 \& got = XPAGet(NULL, "ds9", "file", NULL, bufs, lens, names, messages,
225 \& NXPA);
226 \& for(i=0; i<got; i++){
227 \& if( messages[i] == NULL ){
228 \& /* process buf contents */
229 \& ProcessImage(bufs[i], ...);
230 \& free(bufs[i]);
231 \& }
232 \& else{
233 \& /* error processing */
234 \& fprintf(stderr, "ERROR: %s (%s)\en", messages[i], names[i]);
235 \& }
236 \& if( names[i] )
237 \& free(names[i]);
238 \& if( messages[i] )
239 \& free(messages[i]);
240 \& }
241 .Ve
242 .SH "SEE ALSO"
243 .IX Header "SEE ALSO"
244 See xpa(n) for a list of \s-1XPA\s0 help pages