Debian Codegraph @

cextern/xpa/man/man3/xpanew.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 "xpanew 3"
127 .TH xpanew 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 \&\fBXPANew: create a new \s-1XPA\s0 access point\fR
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 .Vb 1
137 \& #include <xpa.h>
138 \&
139 \& XPA XPANew(char *class, char *name, char *help,
140 \& int (*send_callback)(),
141 \& void *send_data, char *send_mode,
142 \& int (*rec_callback)(),
143 \& void *rec_data, char *rec_mode);
144 .Ve
145 .SH "DESCRIPTION"
146 .IX Header "DESCRIPTION"
147 Create a new \s-1XPA\s0 public access point with the class:name
148 identifier template
149 and enter this access point into the \s-1XPA\s0 name server, so that it
150 can be accessed by external processes. \fIXPANew()\fR returns an \s-1XPA\s0 struct.
151 Note that the length of the class and name designations must be less
152 than or equal to 1024 characters each.
153 .PP
154 The \s-1XPA\s0 name server daemon, xpans, will be started automatically if it
155 is not running already (assuming it can be found in the path). The
156 program's ip address and listening port are specified by the
157 environment variable \s-1XPA_NSINET\s0, which takes the form :. If
158 no such environment variable exists, then xpans is started on the
159 current machine listening on port 14285. It also uses 14286 as a
160 known port for its public access point (so that routines do not have
161 to go to the name server to find the name server ip and port!)
162 As of \s-1XPA\s0 2.1.1, version information is exchanged between the xpans
163 process and the new access point. If the access point uses an \s-1XPA\s0
164 major/minor version newer than xpans, a warning is issued by both processes,
165 since mixing of new servers and old xpa programs (xpaset, xpaget,
166 xpans, etc.) is not likely to work. You can turn off the warning
167 message by setting the \s-1XPA_VERSIONCHECK\s0 environment variable to \*(L"false\*(R".
168 .PP
169 The help string is meant to be returned by a request from xpaget:
170 .PP
171 .Vb 1
172 \& xpaget class:name \-help
173 .Ve
174 .PP
175 A send_callback and/or a receive_callback can be specified; at
176 least one of them must be specified.
177 .PP
178 A send_callback can be specified that will be executed in response to
179 an external request from the xpaget program, the \fIXPAGet()\fR routine, or
180 \&\fIXPAGetFd()\fR routine. This callback is used to send data to the
181 requesting client.
182 .PP
183 The calling sequence for \fIsend_callback()\fR is:
184 .PP
185 .Vb 7
186 \& int send_callback(void *send_data, void *call_data,
187 \& char *paramlist, char **buf, size_t *len)
188 \& {
189 \& XPA xpa = (XPA)call_data;
190 \& ...
191 \& return(stat);
192 \& }
193 .Ve
194 .PP
195 The send_mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R"
196 The following keywords are recognized:
197 .PP
198 .Vb 4
199 \& key value default explanation
200 \& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
201 \& acl true/false true enable access control
202 \& freebuf true/false true free buf after callback completes
203 .Ve
204 .PP
205 The call_data should be recast to the \s-1XPA\s0 struct as shown. In
206 addition, client-specific data can be passed to the callback in
207 send_data.
208 .PP
209 The paramlist will be supplied by the client as qualifying parameters
210 for the callback. There are two ways in which the \fIsend_callback()\fR
211 routine can send data back to the client:
212 .PP
213 1. The \fIsend_callback()\fR routine can fill in a buffer and pass back a
214 pointer to this buffer. An integer len also is returned to specify the
215 number of bytes of data in buf. \s-1XPA\s0 will send this buffer to the
216 client after the callback is complete.
217 .PP
218 2. The send_callback can send data directly to the client by writing
219 to the fd pointed by the macro:
220 .PP
221 .Vb 1
222 \& xpa_datafd(xpa)
223 .Ve
224 .PP
225 Note that this fd is of the kind returned by \fIsocket()\fR or \fIopen()\fR.
226 .PP
227 If a buf has been allocated by a standard malloc routine, filled, and
228 returned to \s-1XPA\s0, then freebuf generally is set so that the buffer will
229 be freed automatically when the callback is completed and data has
230 been sent to the client. If a static buf is returned, freebuf should
231 be set to false to avoid a system error when freeing static storage.
232 Note that default value for freebuf implies that the callback will
233 allocate a buffer rather than use static storage.
234 .PP
235 On the other hand, if buf is dynamically allocated using a method
236 other than a standard malloc/calloc/realloc routine (e.g. using Perl's
237 memory allocation and garbage collection scheme), then it is necessary
238 to tell \s-1XPA\s0 how to free the allocated buffer. To do this, use the
239 \&\fIXPASetFree()\fR routine within your callback:
240 .PP
241 .Vb 1
242 \& void XPASetFree(XPA xpa, void (*myfree)(void *), void *myfree_ptr);
243 .Ve
244 .PP
245 The first argument is the usual \s-1XPA\s0 handle. The second argument is the
246 special routine to call to free your allocated memory. The third
247 argument is an optional pointer. If not \s-1NULL\s0, the specified free
248 routine is called with that pointer as its sole argument. If \s-1NULL\s0, the
249 free routine is called with the standard buf pointer as its sole
250 argument. This is useful in cases where there is a mapping between the
251 buffer pointer and the actual allocated memory location, and the
252 special routine is expecting to be passed the former.
253 .PP
254 If, while the callback performs its processing, an error occurs that
255 should be communicated to the client, then the routine XPAError should be
256 called:
257 .PP
258 .Vb 1
259 \& XPAError(XPA xpa, char *s);
260 .Ve
261 .PP
262 where s is an arbitrary error message. The returned error message
263 string will be of the form:
264 .PP
265 .Vb 1
266 \& XPA$ERROR [error] (class:name ip:port)
267 .Ve
268 .PP
269 If the callback wants to send a specific acknowledgment message back
270 to the client, the routine XPAMessage can be called:
271 .PP
272 .Vb 1
273 \& XPAMessage(XPA xpa, char *s);
274 .Ve
275 .PP
276 where s is an arbitrary error message. The returned error message
277 string will be of the form:
278 .PP
279 .Vb 1
280 \& XPA$MESSAGE [message] (class:name ip:port)
281 .Ve
282 .PP
283 Otherwise, a standard acknowledgment is sent back to the client
284 after the callback is completed.
285 .PP
286 The callback routine should return 0 if no error occurs, or \-1 to
287 signal an error.
288 .PP
289 A receive_callback can be specified that will be executed in response
290 to an external request from the xpaset program, or the XPASet (or
291 \&\fIXPASetFd()\fR) routine. This callback is used to process data received
292 from an external process.
293 .PP
294 The calling sequence for receive_callback is:
295 .PP
296 .Vb 7
297 \& int receive_callback(void *receive_data, void *call_data,
298 \& char *paramlist, char *buf, size_t len)
299 \& {
300 \& XPA xpa = (XPA)call_data;
301 \& ...
302 \& return(stat);
303 \& }
304 .Ve
305 .PP
306 The mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R"
307 The following keywords are recognized:
308 .PP
309 .Vb 6
310 \& key value default explanation
311 \& \-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
312 \& acl true/false true enable access control
313 \& buf true/false true server expects data bytes from client
314 \& fillbuf true/false true read data into buf before executing callback
315 \& freebuf true/false true free buf after callback completes
316 .Ve
317 .PP
318 The call_data should be recast to the \s-1XPA\s0 struct as shown. In
319 addition, client-specific data can be passed to the callback in
320 receive_data.
321 .PP
322 The paramlist will be supplied by the client. In addition, if the
323 receive_mode keywords buf and fillbuf are true, then on entry into the
324 \&\fIreceive_callback()\fR routine, buf will contain the data sent by the
325 client. If buf is true but fillbuf is false, it becomes the callback's
326 responsibility to retrieve the data from the client, using the data fd
327 pointed to by the macro xpa_datafd(xpa). If freebuf is true, then buf
328 will be freed when the callback is complete.
329 .PP
330 If, while the callback is performing its processing, an error occurs
331 that should be communicated to the client, then the routine XPAError
332 can be called:
333 .PP
334 .Vb 1
335 \& XPAError(XPA xpa, char *s);
336 .Ve
337 .PP
338 where s is an arbitrary error message.
339 .PP
340 The callback routine should return 0 if no error occurs, or \-1 to
341 signal an error.
342 .SH "SEE ALSO"
343 .IX Header "SEE ALSO"
344 See xpa(n) for a list of \s-1XPA\s0 help pages