Debian Codegraph @

cextern/xpa/man/mann/xpacommon.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 "xpacommon n"
127 .TH xpacommon 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 \&\fBXPACommon: Getting Common Information About Access Points\fR
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 There are various kinds of generic information you can retrieve about
137 an \s-1XPA\s0 access point by using the xpaget command.
138 .SH "DESCRIPTION"
139 .IX Header "DESCRIPTION"
140 You can find out which \s-1XPA\s0 access points have been registered with
141 the currently running
142 \&\s-1XPA\s0 name server
143 by executing the
144 xpaget
145 command to retrieve info from the \s-1XPA\s0 name server:
146 .PP
147 .Vb 1
148 \& xpaget xpans
149 .Ve
150 .PP
151 If, for example, the
152 stest test server program
153 is running, the following \s-1XPA\s0 access points will be returned (the specifics
154 of the returned info will vary for different machines and users):
155 .PP
156 .Vb 4
157 \& XPA xpa gs 838e2f67:1262 eric
158 \& XPA xpa1 gs 838e2f67:1266 eric
159 \& XPA c_xpa gs 838e2f67:1267 eric
160 \& XPA i_xpa i 838e2f67:1268 eric
161 .Ve
162 .PP
163 Note that access to this information is subject to the usual
164 \&\s-1XPA\s0 Access Control restrictions.
165 .PP
166 Each \s-1XPA\s0 access point supports a number of reserved sub-commands that provide
167 access to different kinds of information, e.g. the access control for
168 that access point. These sub-commands can be executed by using
169 xpaset
170 or
171 xpaget
172 at the command line, or
173 \&\fIXPAGet()\fR
174 or
175 \&\fIXPASet()\fR
176 in programs, e.g:
177 .PP
178 .Vb 3
179 \& xpaget ds9 \-acl
180 \& xpaget ds9 \-help
181 \& xpaget ds9 env FOO
182 \&
183 \& xpaset \-p ds9 env FOO foofoo
184 .Ve
185 .PP
186 With the exception of \fB\-help\fR and \fB\-version\fR, reserved
187 sub-commands are available only on the machine on which the \s-1XPA\s0 server
188 itself is running.
189 .PP
190 The following reserved sub-commands are defined for all access points:
191 .IP "\(bu" 4
192 \&\fB\-acl\fR get (set) the access control list [options: host type acl, for set]
193 .Sp
194 The 'xpaset' option allows you to add a new acl for a given host, or change
195 the acl for an existing host. See
196 \&\s-1XPA\s0 Access Control
197 for more information.
198 This access point is available only on the server machine.
199 .IP "\(bu" 4
200 \&\fB\-env\fR get (set) an environment variable [options: name (value, for set)]
201 .Sp
202 The 'xpaget' option will return the value of the named environment
203 variable. The 'xpaset' option will set the value of the names
204 variable to the specified value.
205 This access point is available only on the server machine.
206 (Please be advised that we have had problems setting environment
207 variables in static Tcl/Tk programs such as ds9 running under Linux.)
208 .IP "\(bu" 4
209 \&\fB\-clipboard\fR set(get) information on a named clipboard
210 .Sp
211 Clients can store \s-1ASCII\s0 state information on any number of named
212 clipboards. Clipboards of the same name created by clients on
213 different machines are kept separate. The syntax for creating a
214 clipboard is:
215 .Sp
216 .Vb 2
217 \& [data] | xpaset [server] \-clipboard add|append [clipboard_name]
218 \& xpaset \-p [server] \-clipboard delete [clipboard_name]
219 .Ve
220 .Sp
221 Use \*(L"add\*(R" to create a new clipboard or replace the contents of an existing
222 one. Use \*(L"append\*(R" to append to an existing clipboard.
223 .Sp
224 Information on a named clipboard is retrieved using:
225 .Sp
226 .Vb 1
227 \& xpaget [server] \-clipboard [clipboard_name]
228 .Ve
229 .IP "\(bu" 4
230 \&\fB\-exec\fR set: execute commands from buffer [options: none]
231 .Sp
232 If \-exec is specified in the paramlist of an 'xpaset' call, then further
233 sub-commands will be retrieved from the data buffer.
234 .IP "\(bu" 4
235 \&\fB\-help\fR get: return help string for this \s-1XPA\s0 or sub-command [options: name (for sub\-commands)]
236 .Sp
237 Each \s-1XPA\s0 access point and each \s-1XPA\s0 sub-command can have a help string
238 associated with it that is specified when the access point is defined.
239 The \-help option will return this help string. For \s-1XPA\s0 access points
240 that contain user-defined sub-commands, you can get the help string
241 for a particular sub-command by specifying its name, or else get the
242 help strings for all sub-commands if not name is specified.
243 .IP "\(bu" 4
244 \&\fB\-ltimeout\fR get (set) the long timeout value [options: seconds|reset]
245 .Sp
246 The 'xpaget' option will return the value of the long timeout (in seconds).
247 The 'xpaset' option will set the value of the long timeout. If \*(L"reset\*(R" is
248 specified, then the timeout value will be reset to the default value.
249 .IP "\(bu" 4
250 \&\fB\-nsconnect\fR set: re-establish name server connection to all \s-1XPA\s0's [options: none]
251 .Sp
252 If the
253 \&\s-1XPA\s0 Name Server (xpans)
254 process has terminated unexpectedly and then re-started, this
255 sub-command can be used to re-establish the connection. You use it by
256 sending the command to the [name:port] or [file] of the access point
257 instead of to the \s-1XPA\s0 name (since the latter requires the xpans
258 connection!):
259 .Sp
260 .Vb 1
261 \& xpaset \-p 838e2f67:1268 \-nsconnect
262 .Ve
263 .Sp
264 See xpans for more information.
265 .IP "\(bu" 4
266 \&\fB\-nsdisconnect\fR set: break name server connection to all \s-1XPA\s0's [options: none]
267 .Sp
268 This sub-command will terminate the connection to the
269 \&\s-1XPA\s0 Name Server (xpans), thereby making
270 all access points inaccessible except through their underlying [name:port]
271 or [file] identifiers. I forget why we added it, it seems pretty useless.
272 .IP "\(bu" 4
273 \&\fB\-stimeout\fR get (set) the short timeout value [options: seconds|reset]
274 .Sp
275 The 'xpaget' option will return the value of the short timeout (in seconds).
276 The 'xpaset' option will set the value of the short timeout. If \*(L"reset\*(R" is
277 specified, then the timeout value will be reset to the default value.
278 .IP "\(bu" 4
279 \&\fB\-remote\fR set: register xpa with remote server [options: host[:port] [acl]] [\-proxy]
280 .Sp
281 This sub-command will register the \s-1XPA\s0 access point with the \s-1XPA\s0 name
282 server (xpans) on the specified host (which must already be running).
283 The specified host also is given access control to the access point,
284 using the specified acl or the default acl of \*(L"+\*(R" (meaning the remote
285 host can xpaset, xpaget, xpainfo or xpaaccess). If the acl is
286 specified as \*(L"\-\*(R", then the access point is unregistered.
287 See Communication Between Machines
288 for more information on how this sub-command is used.
289 .IP "\(bu" 4
290 \&\fB\-version\fR get: return \s-1XPA\s0 version string [options: none]
291 .Sp
292 The version refers to the version of \s-1XPA\s0 used to define this access point
293 (currently something like 2.0).
294 .PP
295 You can add your own reserved commands to all \s-1XPA\s0 access points by using the
296 \&\fIXPACmdAdd()\fR
297 routine, passing the \s-1XPA\s0 handle returned by \fI\s-1XPA\s0 XPAGetReserved(void)\fR
298 as the first argument. Note again that these will only be available on the
299 machine where the \s-1XPA\s0 service is running.
300 .SH "SEE ALSO"
301 .IX Header "SEE ALSO"
302 See xpa(n) for a list of \s-1XPA\s0 help pages