Debian Codegraph @

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