.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "send 3pm"
.TH send 3pm "2015-05-03" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Tk::send \- Execute a command in a different application
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
    \fI\f(CI$result\fI\fR = \fI\f(CI$widget\fI\fR\->\fBsend\fR(?\fIoptions\fR,?\fIapp\fR=>\fIcmd\fR?\fIarg arg ...\fR?)
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This method arranges for \fIcmd\fR (and \fIarg\fRs) to be 'sent' to the
application named by \fIapp\fR.  It returns the result or
an error (hence above should probably be 'wrapped' in \fBeval{}\fR and $@ tested).
\&\fIApp\fR may be the name of any application whose main window is
on the display containing the sender's main window;  it need not
be within the same process.
If no \fIarg\fR arguments are present, then the string to be sent
is contained entirely within the \fIcmd\fR argument.  If one or
more \fIarg\fRs are present, they are concatenated separated by white space to
form the string to be sent.
.PP
If the initial arguments of the call begin with ``\-''
they are treated as options.  The following options are
currently defined:
.IP "\fB\-async\fR" 4
.IX Item "-async"
Requests asynchronous invocation.  In this case the \fBsend\fR
command will complete immediately without waiting for \fIcmd\fR
to complete in the target application;  no result will be available
and errors in the sent command will be ignored.
If the target application is in the same process as the sending
application then the \fB\-async\fR option is ignored.
.IP "\fB\-\-\fR" 4
.IX Item "--"
Serves no purpose except to terminate the list of options.  This
option is needed only if \fIapp\fR could contain a leading ``\-''
character.
.SH "APPLICATION NAMES"
.IX Header "APPLICATION NAMES"
The name of an application is set initially from the name of the
program or script that created the application.
You can query and change the name of an application with the
\&\fBappname\fR method.
.SH "WHAT IS A SEND"
.IX Header "WHAT IS A SEND"
The \fBsend\fR mechanism was designed to allow Tcl/Tk applications
to send Tcl Scripts to each other. This does not map very well onto perl/Tk.
Perl/Tk \*(L"sends\*(R" a string to \fIapp\fR, what happens as a result of this
depends on the receiving application. If the other application is a Tcl/Tk4.*
application it will be treated as a Tcl Script. If the \*(L"other\*(R" application is
perl/Tk application (including sends to self) then the string is
passed as an argument to a method call of the following form:
.PP
\&\fI\f(CI$mainwindow\fI\fR\->\fBReceive(\fR\fIstring\fR);
.PP
There is a default (AutoLoaded) \fBTk::Receive\fR which returns an error to the
sending application. A particular application may define its own
\&\fBReceive\fR method in any class in \fBMainWindow\fR's inheritance tree
to do whatever it sees fit. For example it could \fBeval\fR the string,
possibly in a \fBSafe\fR \*(L"compartment\*(R".
.PP
If a Tcl/Tk application \*(L"sends\*(R" anything to a perl/Tk application
then the perl/Tk application would have to attempt to interpret the
incoming string as a Tcl Script. Simple cases are should not be too hard to
emulate (split on white space and treat first element as \*(L"command\*(R" and other
elements as arguments).
.SH "SECURITY"
.IX Header "SECURITY"
The \fBsend\fR command is potentially a serious security loophole,
since any application that can connect to your X server can send
scripts to your applications. Hence the default behaviour outlined above.
(With the availability of \fBSafe\fR it may make sense to relax default behaviour
a little.)
.PP
Unmonitored \fBeval\fR'ing of these incoming \*(L"scripts\*(R" can cause perl to
read and write files and invoke subprocesses under your name.
Host-based access control such as that provided by \fBxhost\fR
is particularly insecure, since it allows anyone with an account
on particular hosts to connect to your server, and if disabled it
allows anyone anywhere to connect to your server.
In order to provide at least a small amount of
security, core Tk checks the access control being used by the server
and rejects incoming sends unless (a) \fBxhost\fR\-style access control
is enabled (i.e. only certain hosts can establish connections) and (b) the
list of enabled hosts is empty.
This means that applications cannot connect to your server unless
they use some other form of authorization
such as that provide by \fBxauth\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\*(L"eval\*(R" in perlfunc, Safe,
system's administrator/corporate security guidelines etc.
.SH "KEYWORDS"
.IX Header "KEYWORDS"
application, name, remote execution, security, send