Debian Codegraph @

cextern/xpa/man/mann/xpaintro.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 "xpaintro n"
127 .TH xpaintro 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 \&\fBXPAIntro: Introduction to the \s-1XPA\s0 Messaging System\fR
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 A brief introduction to the \s-1XPA\s0 messaging system, which provides
137 seamless communication between all kinds of Unix event-driven
138 programs, including X programs, Tcl/Tk programs, and Perl programs.
139 .SH "DESCRIPTION"
140 .IX Header "DESCRIPTION"
141 The \s-1XPA\s0 messaging system provides seamless communication between all
142 kinds of Unix programs, including X programs, Tcl/Tk programs, and
143 Perl programs. It also provides an easy way for users to communicate
144 with these XPA-enabled programs by executing \s-1XPA\s0 client commands in
145 the shell or by utilizing such commands in scripts. Because \s-1XPA\s0 works
146 both at the programming level and the shell level, it is a powerful
147 tool for unifying any analysis environment: users and programmers have
148 great flexibility in choosing the best level or levels at which to
149 access \s-1XPA\s0 services, and client access can be extended or modified
150 easily at any time.
151 .PP
152 A program becomes an XPA-enabled server by defining named points of
153 public access through which data and commands can be exchanged with
154 other client programs (and users). Using standard \s-1TCP\s0 sockets as
155 a transport mechanism, \s-1XPA\s0 supports both single-point and broadcast
156 messaging to and from these servers. It supports direct communication
157 between clients and servers, or indirect communication via an
158 intermediate message bus emulation program. Host-based access control
159 is implemented, as is as the ability to communicate with \s-1XPA\s0 servers
160 across a network.
161 .PP
162 \&\s-1XPA\s0 implements a layered interface that is designed to be useful both
163 to software developers and to users. The interface consists of a
164 library of \s-1XPA\s0 client and server routines for use in programs and a
165 suite of high-level user programs built on top of these libraries.
166 Using the \s-1XPA\s0 library, access points can be added to
167 Tcl/Tk
168 programs,
169 Xt
170 programs, or to Unix programs that use the \s-1XPA\s0 event loop or any
171 event loop based on \fIselect()\fR. Client access subroutines can be added
172 to any Tcl/Tk or Unix program. Client access also is supported at the
173 command line via a suite of high-level programs.
174 .PP
175 The major components of the \s-1XPA\s0 layered interface are:
176 .IP "\(bu" 4
177 A set of \s-1XPA\s0 server routines, centered on
178 \&\fIXPANew()\fR,
179 which are used by \s-1XPA\s0 server programs to tag public access points with
180 string identifiers and to register send and receive callbacks for
181 these access points.
182 .IP "\(bu" 4
183 A set of \s-1XPA\s0 client routines, centered on the
184 \&\fIXPASet()\fR
185 and
186 \&\fIXPAGet()\fR,
187 which are used by external client applications to exchange data and
188 commands with an \s-1XPA\s0 server.
189 .IP "\(bu" 4
190 High-level programs, centered on
191 xpaset
192 and
193 xpaget,
194 which allow data
195 and information to be exchanged with \s-1XPA\s0 server programs from the
196 command line and from scripts. These programs have the command syntax:
197 .Sp
198 .Vb 2
199 \& [data] | xpaset [qualifiers ...]
200 \& xpaget [qualifiers ...]
201 .Ve
202 .IP "\(bu" 4
203 An \s-1XPA\s0 name server program,
204 xpans,
205 through which \s-1XPA\s0 access point names are
206 registered by servers and distributed to clients.
207 .PP
208 Defining an \s-1XPA\s0 access point is easy: a server application calls
209 \&\fIXPANew()\fR,
210 \&\fIXPACmdNew()\fR,
211 or the experimental
212 \&\fIXPAInfoNew()\fR
213 routine to
214 create a named public access point. An \s-1XPA\s0 service can specify \*(L"send\*(R"
215 and \*(L"receive\*(R" callback procedures (or an \*(L"info\*(R" procedure in the case
216 of \fIXPAInfoNew()\fR) to be executed by the program when an external
217 process either sends data or commands to this access point or requests
218 data or information from this access point. Either of the callbacks
219 can be omitted, so that a particular access point can be specified as
220 read-only, read-write, or write-only. Application-specific client
221 data can be associated with these callbacks. Having defined one or
222 more public access points in this way, an \s-1XPA\s0 server program enters
223 its usual event loop (or uses the standard \s-1XPA\s0 event loop).
224 .PP
225 Clients communicate with these \s-1XPA\s0 public access points
226 using programs such as
227 xpaget,
228 xpaset, and
229 xpainfo
230 (at the command line),
231 or routines such as
232 \&\fIXPAGet()\fR,
233 \&\fIXPASet()\fR,
234 and
235 \&\fIXPAInfo()\fR
236 within a program. Both methods require specification of the name of
237 the access point. The xpaget program returns data or other
238 information from an \s-1XPA\s0 server to its standard output, while the
239 xpaset program sends data or commands from its standard input to an
240 \&\s-1XPA\s0 application. The corresponding \s-1API\s0 routines set/get data to/from
241 memory, returning error messages and other info as needed. If a
242 template
243 is used to specify the access point name (e.g., \*(L"ds9*\*(R"), then
244 communication will take place with all servers matching that template.
245 .PP
246 Please note that \s-1XPA\s0 currently is not thread-safe. All \s-1XPA\s0 calls must be
247 in the same thread.
248 .SH "SEE ALSO"
249 .IX Header "SEE ALSO"
250 See xpa(n) for a list of \s-1XPA\s0 help pages