Debian Codegraph @

cextern/xpa/man/man3/xpanslookup.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 "xpanslookup 3"
127 .TH xpanslookup 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 \&\fBXPANSLookup: lookup registered \s-1XPA\s0 access points\fR
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 .Vb 1
137 \& #include <xpa.h>
138 \&
139 \& int XPANSLookup(XPA xpa,
140 \& char *template, char type,
141 \& char ***classes, char ***names,
142 \& char ***methods, char ***infos)
143 .Ve
144 .SH "DESCRIPTION"
145 .IX Header "DESCRIPTION"
146 \&\s-1XPA\s0 routines act on a class:name identifier in such a way
147 that all access points that match the identifier are processed. It is
148 sometimes desirable to choose specific access points from the
149 candidates that match the
150 template. In order to do this, the
151 XPANSLookup routine can be called to return a list of matches, so that
152 specific class:name instances can then be fed to \fIXPAGet()\fR, \fIXPASet()\fR, etc.
153 .PP
154 .Vb 4
155 \& The first argument is an optional XPA struct. If non\-NULL, the
156 \&existing name server connection associated with the specified xpa is
157 \&used to query the xpans name server for matching templates. Otherwise,
158 \&a new (temporary) connection is established with the name server.
159 .Ve
160 .PP
161 The second argument to XPANSLookup is the class:name
162 template
163 to match.
164 .PP
165 The third argument for \fIXPANSLookup()\fR is the type of access and can be
166 any combination of:
167 .PP
168 .Vb 5
169 \& type explanation
170 \& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
171 \& g xpaget calls can be made on this access point
172 \& s xpaset calls can be made on this access point
173 \& i xpainfo calls can be made on this access point
174 .Ve
175 .PP
176 The call typically specifies only one of these at a time.
177 .PP
178 The final arguments are pointers to arrays that will be filled
179 in and returned by the name server. The name server will allocate and
180 return arrays filled with the classes, names, and methods of all \s-1XPA\s0
181 access points that match the template
182 and have the specified type. Also returned are info strings, which
183 generally are used internally by the client routines. These can be
184 ignored (but the strings must be freed). The function returns the
185 number of matches. The returned value can be used to loop through the
186 matches:
187 .PP
188 \&\fBExample:\fR
189 .PP
190 .Vb 1
191 \& #include <xpa.h>
192 \&
193 \& char **classes;
194 \& char **names;
195 \& char **methods;
196 \& char **infos;
197 \& int i, n;
198 \& n = XPANSLookup(NULL, "foo*", "g", &classes, &names, &methods, &infos);
199 \& for(i=0; i<n; i++){
200 \& [more specific checks on possibilities ...]
201 \& [perhaps a call to XPAGet for those that pass, etc. ...]
202 \& /* don\*(Aqt forget to free alloc\*(Aqed strings when done */
203 \& free(classes[i]);
204 \& free(names[i]);
205 \& free(methods[i]);
206 \& free(infos[i]);
207 \& }
208 \& /* free up arrays alloc\*(Aqed by names server */
209 \& if( n > 0 ){
210 \& free(classes);
211 \& free(names);
212 \& free(methods);
213 \& free(infos);
214 \& }
215 .Ve
216 .PP
217 The specified
218 template
219 also can be a host:port specification, for example:
220 .PP
221 .Vb 1
222 \& myhost:12345
223 .Ve
224 .PP
225 In this case, no connection is made to the name server. Instead, the
226 call will return one entry such that the ip array contains the ip for
227 the specified host and the port array contains the port. The class
228 and name entries are set to the character \*(L"?\*(R", since the class and
229 name of the access point are not known.
230 .SH "SEE ALSO"
231 .IX Header "SEE ALSO"
232 See xpa(n) for a list of \s-1XPA\s0 help pages