Debian Codegraph @

cextern/xpa/man/mann/xpatcl.n

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 "xpatcl n"
127 .TH xpatcl n "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 \&\fBXPATcl: the \s-1XPA\s0 Interface to the Tcl/Tk Environment\fR
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 Tcl/Tk programs can act as \s-1XPA\s0 clients and/or servers using the Tcl
137 interface to \s-1XPA\s0 that is contained in the libtclxpa.so shared object.
138 .PP
139 \&\fBServer Routines\fR
140 .PP
141 .Vb 11
142 \& set xpa [xpanew class name help sproc sdata smode rproc rdata rmode]
143 \& xpafree xpa
144 \& set xpa [xpanew class name help iproc idata imode]
145 \& set xpa [xpacmdnew class name]
146 \& xpacmdadd xpa name help sproc sdata smode rproc rdata rmode
147 \& xpacmddel xpa cmd
148 \& set val [xparec xpa option]
149 \& options: name, class, method, cmdfd, datafd, cmdchan, datachan
150 \& xpasetbuf xpa buf len
151 \& xpaerror xpa message
152 \& xpamessage xpa message
153 .Ve
154 .PP
155 \&\fBClient Routines\fR
156 .PP
157 .Vb 11
158 \& set xpa [xpaopen mode]
159 \& xpaclose xpa
160 \& set got [xpaget xpa template paramlist mode bufs lens names errs n]
161 \& set got [xpaget xpa template paramlist mode chans names errs n]
162 \& set got [xpaset xpa template paramlist mode buf len names errs n]
163 \& set got [xpasetfd xpa template paramlist mode chan names errs n]
164 \& set got [xpainfo xpa template paramlist mode names errs n]
165 \& # NB: 2.1 calling sequence change
166 \& # set got [xpaaccess template type] (2.0.5)
167 \& set got [xpaaccess xpa template paramlist mode names errs n]
168 \& set got [xpanslookup template type classes names methods]
169 .Ve
170 .SH "DESCRIPTION"
171 .IX Header "DESCRIPTION"
172 You can call \fIXPANew()\fR, \fIXPACmdNew()\fR, or \fIXPAInfoNew()\fR within a C
173 routine to add C\-based \s-1XPA\s0 server callbacks to a TCL/Tk program that
174 uses a Tcl/Tk event loop (either \fIvwait()\fR or the Tk event loop);
175 Such a program does not need or want to use the \s-1XPA\s0 event loop.
176 Therefore, in order to add \s-1XPA\s0 access points to the Tcl/Tk loop, the
177 following routine should be called beforehand:
178 .PP
179 .Vb 1
180 \& int XPATclAddInput(XPA xpa);
181 .Ve
182 .PP
183 Normally, the xpa argument is \s-1NULL\s0, meaning that all current \s-1XPA\s0
184 access points are registered with the event loop. However, if a
185 single \s-1XPA\s0 access point is to be added (i.e., after the event loop is
186 started) then the handle of that \s-1XPA\s0 access point can be passed to
187 this routine.
188 .PP
189 The significance of the \s-1XPA/TCL\s0 interface goes beyond the support for
190 using \s-1XPA\s0 inside C code. The interface allows you to write \s-1XPA\s0
191 servers and to make calls to the \s-1XPA\s0 client interface within the Tcl
192 environment using the Tcl language directly. The XPA/Tcl
193 interface can be loaded using the following package command:
194 .PP
195 .Vb 1
196 \& package require tclxpa 2.0
197 .Ve
198 .PP
199 Alternatively, you can load the shared object (called libtclxpa.so ) directly:
200 .PP
201 .Vb 1
202 \& load .../libtclxpa.so tclxpa
203 .Ve
204 .PP
205 Once the tclxpa package is loaded, you can use Tcl versions of \s-1XPA\s0
206 routines to define \s-1XPA\s0 servers or make client \s-1XPA\s0 calls. The
207 interface for these routines is designed to match the Unix \s-1XPA\s0
208 interface as nearly as possible. Please refer to
209 \&\s-1XPA\s0 Servers
210 and
211 \&\s-1XPA\s0 Clients
212 for general information about these routines.
213 .PP
214 The file test.tcl in the \s-1XPA\s0 source directory gives examples for using the
215 XPA/Tcl interface.
216 .PP
217 The following notes describe the minor differences between the interfaces.
218 .PP
219 \&\fBXPANew\fR
220 .PP
221 .Vb 1
222 \& set xpa [xpanew class name help sproc sdata smode rproc rdata rmode]
223 .Ve
224 .PP
225 rproc and sproc routines are routines. The calling sequence of the
226 rproc routine is identical to its C counterpart:
227 .PP
228 .Vb 1
229 \& proc rec_cb { xpa client_data paramlist buf len } { ... }
230 .Ve
231 .PP
232 The sproc routine, however is slightly different from its C counterpart
233 because of the difficulty of passing data back from the callback to C:
234 .PP
235 .Vb 1
236 \& proc sendcb { xpa client_data paramlist } { ... }
237 .Ve
238 .PP
239 Note that the C\-based server's char **buf and int *len arguments are
240 missing from the Tcl callback. This is because we did not know how to
241 fill buf with data and pass it back to the C routines for communication
242 with the client. Instead, the Tcl server callback uses the following
243 routine to set buf and len:
244 .PP
245 .Vb 1
246 \& xpasetbuf xpa buf len
247 .Ve
248 .PP
249 where:
250 .PP
251 .Vb 5
252 \& arg explanation
253 \& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
254 \& xpa the first argument of the server callback
255 \& buf the data to be returned to the client
256 \& len data length in bytes, (if absent, use length of the buf object)
257 .Ve
258 .PP
259 When this routine is called, a copy of buf is saved for transmission to
260 the client.
261 .PP
262 The fact that buf is duplicated means that \s-1TCL\s0 server writers might wish to
263 perform the I/O directly within the callback, rather than have \s-1XPA\s0 do it
264 automatically at the end of the routine. To do this, set:
265 .PP
266 .Vb 1
267 \& fillbuf=false
268 .Ve
269 .PP
270 in the xpanew smode and then perform I/O through the Tcl channel
271 obtained from:
272 .PP
273 .Vb 1
274 \& set dchan [xparec $xpa datachan]
275 .Ve
276 .PP
277 where:
278 .PP
279 .Vb 5
280 \& arg explanation
281 \& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
282 \& xpa the first argument of the server callback
283 \& datachan literal string "datachan" that returns the data channel
284 \& len data length in bytes, (if absent, use length of the buf object)
285 .Ve
286 .PP
287 \&\s-1NB:\s0 datachan and cmdchan are not available under Windows. It is
288 necessary to use the \*(L"raw\*(R" equivalents: datafd and cmdfd.
289 .PP
290 The same considerations apply to the rproc for receive servers: a copy
291 of the incoming data is generated to pass to the receive callback. This
292 copy again can be avoided by using \*(L"fillbuf=false\*(R" in the rmode and then
293 reading the incoming data from datachan.
294 .PP
295 The send and receive callback routines can use the xpaerror and xpamessage
296 routines to send errors and messages back to the client. If you also
297 want tcl itself to field an error condition, use the standard return call:
298 .PP
299 .Vb 1
300 \& return ?\-code c? ?\-errorinfo i? ?\-errorcode ec? string
301 .Ve
302 .PP
303 See the Tcl man page for more info.
304 .PP
305 \&\fBXPARec\fR
306 .PP
307 The Tcl xparec procedure supplies server routines with access to information
308 that is available via macros in the C interface:
309 .PP
310 .Vb 1
311 \& set val [xparec xpa <option>]
312 .Ve
313 .PP
314 where option is: name, class, method, cmdfd, datafd, cmdchan,
315 datachan. Note that two additional identifiers, cmdchan and datachan,
316 have been added to to provide Tcl channels corresponding to datafd and
317 cmdfd. (These latter might still be retrieved in Tcl and passed back
318 to a C routines.) An additional option called \*(L"version\*(R" can be used to
319 determine the \s-1XPA\s0 version used to build the Tcl interface. Note that
320 the standard options require a valid \s-1XPA\s0 handle, but \*(L"version\*(R" does
321 not (since it simply reports the value of the \s-1XPA_VERSION\s0 definition
322 in the \s-1XPA\s0 source include file).
323 .PP
324 \&\s-1NB:\s0 datachan and cmdchan are not available under Windows. It is
325 necessary to use the \*(L"raw\*(R" equivalents: datafd and cmdfd.
326 .PP
327 .Vb 12
328 \& macro explanation
329 \& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
330 \& class class of this xpa
331 \& name name of this xpa
332 \& method method string (inet or local connect info)
333 \& cmdchan Tcl channel of command socket
334 \& datachan Tcl channel of data socket
335 \& cmdfd fd of command socket
336 \& datafd fd of data socket
337 \& sendian endian\-ness of server ("little" or "big")
338 \& cendian endian\-ness of client ("little" or "big"
339 \& version XPA version used to build this code
340 .Ve
341 .PP
342 Under Windows, the Tcl event handler cannot automatically sense when an
343 \&\s-1XPA\s0 socket is ready for \s-1IO\s0 (i.e. \fITcl_CreateFileHandler()\fR is not available
344 under Windows). The Windows Tcl event handler therefore must be awakened
345 occasionally for check for \s-1XPA\s0 events. This is done using the standard
346 \&\fITcl_SetMaxBlockTime()\fR call. The time parameter is defined in tclloop.c
347 and is currently set to 1000 microseconds (1/1000 of a second).
348 .PP
349 The version option can be used to differentiate between source code versions.
350 It was created to support legacy Tcl code that needs to maintain the 2.0.5
351 calling sequence for xpaaccess. You can use a version test such as:
352 .PP
353 .Vb 5
354 \& if [catch { xparec "" version } version] {
355 \& puts "pre\-2.1.0e"
356 \& } else {
357 \& puts [split $version .]
358 \& }
359 .Ve
360 .SH "SEE ALSO"
361 .IX Header "SEE ALSO"
362 See xpa(n) for a list of \s-1XPA\s0 help pages