man/mann/send.n - toolchains/skids - Git at Google

 '\"
 '\" Copyright (c) 1990-1994 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
 '\" RCS: @(#) $Id: send.n,v 1.3 1999/04/16 01:51:09 stanton Exp $
 '\"
 '\" The definitions below are for supplemental macros used in Tcl/Tk
 '\" manual entries.
 '\"
 '\" .AP type name in/out ?indent?
 '\"	Start paragraph describing an argument to a library procedure.
 '\"	type is type of argument (int, etc.), in/out is either "in", "out",
 '\"	or "in/out" to describe whether procedure reads or modifies arg,
 '\"	and indent is equivalent to second arg of .IP (shouldn't ever be
 '\"	needed;  use .AS below instead)
 '\"
 '\" .AS ?type? ?name?
 '\"	Give maximum sizes of arguments for setting tab stops.  Type and
 '\"	name are examples of largest possible arguments that will be passed
 '\"	to .AP later.  If args are omitted, default tab stops are used.
 '\"
 '\" .BS
 '\"	Start box enclosure.  From here until next .BE, everything will be
 '\"	enclosed in one large box.
 '\"
 '\" .BE
 '\"	End of box enclosure.
 '\"
 '\" .CS
 '\"	Begin code excerpt.
 '\"
 '\" .CE
 '\"	End code excerpt.
 '\"
 '\" .VS ?version? ?br?
 '\"	Begin vertical sidebar, for use in marking newly-changed parts
 '\"	of man pages.  The first argument is ignored and used for recording
 '\"	the version when the .VS was added, so that the sidebars can be
 '\"	found and removed when they reach a certain age.  If another argument
 '\"	is present, then a line break is forced before starting the sidebar.
 '\"
 '\" .VE
 '\"	End of vertical sidebar.
 '\"
 '\" .DS
 '\"	Begin an indented unfilled display.
 '\"
 '\" .DE
 '\"	End of indented unfilled display.
 '\"
 '\" .SO
 '\"	Start of list of standard options for a Tk widget.  The
 '\"	options follow on successive lines, in four columns separated
 '\"	by tabs.
 '\"
 '\" .SE
 '\"	End of list of standard options for a Tk widget.
 '\"
 '\" .OP cmdName dbName dbClass
 '\"	Start of description of a specific option.  cmdName gives the
 '\"	option's name as specified in the class command, dbName gives
 '\"	the option's name in the option database, and dbClass gives
 '\"	the option's class in the option database.
 '\"
 '\" .UL arg1 arg2
 '\"	Print arg1 underlined, then print arg2 normally.
 '\"
 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
 '\"
 '\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
 .if t .wh -1.3i ^B
 .nr ^l \n(.l
 .ad b
 '\"	# Start an argument description
 .de AP
 .ie !"\\$4"" .TP \\$4
 .el \{\
 .   ie !"\\$2"" .TP \\n()Cu
 .   el          .TP 15
 .\}
 .ta \\n()Au \\n()Bu
 .ie !"\\$3"" \{\
 \&\\$1	\\fI\\$2\\fP	(\\$3)
 .\".b
 .\}
 .el \{\
 .br
 .ie !"\\$2"" \{\
 \&\\$1	\\fI\\$2\\fP
 .\}
 .el \{\
 \&\\fI\\$1\\fP
 .\}
 .\}
 ..
 '\"	# define tabbing values for .AP
 .de AS
 .nr )A 10n
 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 .nr )B \\n()Au+15n
 .\"
 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 ..
 .AS Tcl_Interp Tcl_CreateInterp in/out
 '\"	# BS - start boxed text
 '\"	# ^y = starting y location
 '\"	# ^b = 1
 .de BS
 .br
 .mk ^y
 .nr ^b 1u
 .if n .nf
 .if n .ti 0
 .if n \l'\\n(.lu\(ul'
 .if n .fi
 ..
 '\"	# BE - end boxed text (draw box now)
 .de BE
 .nf
 .ti 0
 .mk ^t
 .ie n \l'\\n(^lu\(ul'
 .el \{\
 .\"	Draw four-sided box normally, but don't draw top of
 .\"	box if the box started on an earlier page.
 .ie !\\n(^b-1 \{\
 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 .\}
 .el \}\
 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 .\}
 .\}
 .fi
 .br
 .nr ^b 0
 ..
 '\"	# VS - start vertical sidebar
 '\"	# ^Y = starting y location
 '\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
 .de VS
 .if !"\\$2"" .br
 .mk ^Y
 .ie n 'mc \s12\(br\s0
 .el .nr ^v 1u
 ..
 '\"	# VE - end of vertical sidebar
 .de VE
 .ie n 'mc
 .el \{\
 .ev 2
 .nf
 .ti 0
 .mk ^t
 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 .sp -1
 .fi
 .ev
 .\}
 .nr ^v 0
 ..
 '\"	# Special macro to handle page bottom:  finish off current
 '\"	# box/sidebar if in box/sidebar mode, then invoked standard
 '\"	# page bottom macro.
 .de ^B
 .ev 2
 'ti 0
 'nf
 .mk ^t
 .if \\n(^b \{\
 .\"	Draw three-sided box if this is the box's first page,
 .\"	draw two sides but no top otherwise.
 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 .\}
 .if \\n(^v \{\
 .nr ^x \\n(^tu+1v-\\n(^Yu
 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 .\}
 .bp
 'fi
 .ev
 .if \\n(^b \{\
 .mk ^y
 .nr ^b 2
 .\}
 .if \\n(^v \{\
 .mk ^Y
 .\}
 ..
 '\"	# DS - begin display
 .de DS
 .RS
 .nf
 .sp
 ..
 '\"	# DE - end display
 .de DE
 .fi
 .RE
 .sp
 ..
 '\"	# SO - start of list of standard options
 .de SO
 .SH "STANDARD OPTIONS"
 .LP
 .nf
 .ta 5.5c 11c
 .ft B
 ..
 '\"	# SE - end of list of standard options
 .de SE
 .fi
 .ft R
 .LP
 See the \\fBoptions\\fR manual entry for details on the standard options.
 ..
 '\"	# OP - start of full description for a single option
 .de OP
 .LP
 .nf
 .ta 4c
 Command-Line Name:	\\fB\\$1\\fR
 Database Name:	\\fB\\$2\\fR
 Database Class:	\\fB\\$3\\fR
 .fi
 .IP
 ..
 '\"	# CS - begin code excerpt
 .de CS
 .RS
 .nf
 .ta .25i .5i .75i 1i
 ..
 '\"	# CE - end code excerpt
 .de CE
 .fi
 .RE
 ..
 .de UL
 \\$1\l'|0\(ul'\\$2
 ..
 .TH send n 4.0 Tk "Tk Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 send \- Execute a command in a different application
 .SH SYNOPSIS
 \fBsend ?\fIoptions\fR? \fIapp cmd \fR?\fIarg arg ...\fR?
 .BE

 .SH DESCRIPTION
 .PP
 This command arranges for \fIcmd\fR (and \fIarg\fRs) to be executed in the
 application named by \fIapp\fR.  It returns the result or
 error from that command execution.
 \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 command to be executed is
 contained entirely within the \fIcmd\fR argument.  If one or
 more \fIarg\fRs are present, they are concatenated to form the
 command to be executed, just as for the \fBeval\fR command.
 .PP
 If the initial arguments of the command begin with ``\-''
 they are treated as options.  The following options are
 currently defined:
 .TP
 \fB\-async\fR
 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.
 .TP
 \fB\-displayof\fR \fIpathName\fR
 Specifies that the target application's main window is on the display
 of the window given by \fIpathName\fR, instead of the display containing
 the application's main window.
 .TP
 \fB\-\|\-\fR
 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"
 .PP
 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
 \fBtk appname\fR command.

 .SH "DISABLING SENDS"
 .PP
 If the \fBsend\fR command is removed from an application (e.g.
 with the command \fBrename send {}\fR) then the application
 will not respond to incoming send requests anymore,  nor will it
 be able to issue outgoing requests.
 Communication can be reenabled by invoking the \fBtk appname\fR
 command.

 .SH SECURITY
 .PP
 The \fBsend\fR command is potentially a serious security loophole. On Unix,
 any application that can connect to your X server can send
 scripts to your applications.
 These incoming scripts can use Tcl to read and
 write your 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, 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.
 .VS
 Under Windows, \fBsend\fR is currently disabled.  Most of the
 functionality is provided by the \fBdde\fR command instead.
 .VE
 .SH KEYWORDS
 .VS
 application, dde, name, remote execution, security, send
 .VE
	'\"
	'\" Copyright (c) 1990-1994 The Regents of the University of California.
	'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
	'\"
	'\" See the file "license.terms" for information on usage and redistribution
	'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
	'\"
	'\" RCS: @(#) $Id: send.n,v 1.3 1999/04/16 01:51:09 stanton Exp $
	'\"
	'\" The definitions below are for supplemental macros used in Tcl/Tk
	'\" manual entries.
	'\"
	'\" .AP type name in/out ?indent?
	'\" Start paragraph describing an argument to a library procedure.
	'\" type is type of argument (int, etc.), in/out is either "in", "out",
	'\" or "in/out" to describe whether procedure reads or modifies arg,
	'\" and indent is equivalent to second arg of .IP (shouldn't ever be
	'\" needed; use .AS below instead)
	'\"
	'\" .AS ?type? ?name?
	'\" Give maximum sizes of arguments for setting tab stops. Type and
	'\" name are examples of largest possible arguments that will be passed
	'\" to .AP later. If args are omitted, default tab stops are used.
	'\"
	'\" .BS
	'\" Start box enclosure. From here until next .BE, everything will be
	'\" enclosed in one large box.
	'\"
	'\" .BE
	'\" End of box enclosure.
	'\"
	'\" .CS
	'\" Begin code excerpt.
	'\"
	'\" .CE
	'\" End code excerpt.
	'\"
	'\" .VS ?version? ?br?
	'\" Begin vertical sidebar, for use in marking newly-changed parts
	'\" of man pages. The first argument is ignored and used for recording
	'\" the version when the .VS was added, so that the sidebars can be
	'\" found and removed when they reach a certain age. If another argument
	'\" is present, then a line break is forced before starting the sidebar.
	'\"
	'\" .VE
	'\" End of vertical sidebar.
	'\"
	'\" .DS
	'\" Begin an indented unfilled display.
	'\"
	'\" .DE
	'\" End of indented unfilled display.
	'\"
	'\" .SO
	'\" Start of list of standard options for a Tk widget. The
	'\" options follow on successive lines, in four columns separated
	'\" by tabs.
	'\"
	'\" .SE
	'\" End of list of standard options for a Tk widget.
	'\"
	'\" .OP cmdName dbName dbClass
	'\" Start of description of a specific option. cmdName gives the
	'\" option's name as specified in the class command, dbName gives
	'\" the option's name in the option database, and dbClass gives
	'\" the option's class in the option database.
	'\"
	'\" .UL arg1 arg2
	'\" Print arg1 underlined, then print arg2 normally.
	'\"
	'\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
	'\"
	'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
	.if t .wh -1.3i ^B
	.nr ^l \n(.l
	.ad b
	'\" # Start an argument description
	.de AP
	.ie !"\\$4"" .TP \\$4
	.el \{\
	. ie !"\\$2"" .TP \\n()Cu
	. el .TP 15
	.\}
	.ta \\n()Au \\n()Bu
	.ie !"\\$3"" \{\
	\&\\$1 \\fI\\$2\\fP (\\$3)
	.\".b
	.\}
	.el \{\
	.br
	.ie !"\\$2"" \{\
	\&\\$1 \\fI\\$2\\fP
	.\}
	.el \{\
	\&\\fI\\$1\\fP
	.\}
	.\}
	..
	'\" # define tabbing values for .AP
	.de AS
	.nr )A 10n
	.if !"\\$1"" .nr )A \\w'\\$1'u+3n
	.nr )B \\n()Au+15n
	.\"
	.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
	.nr )C \\n()Bu+\\w'(in/out)'u+2n
	..
	.AS Tcl_Interp Tcl_CreateInterp in/out
	'\" # BS - start boxed text
	'\" # ^y = starting y location
	'\" # ^b = 1
	.de BS
	.br
	.mk ^y
	.nr ^b 1u
	.if n .nf
	.if n .ti 0
	.if n \l'\\n(.lu\(ul'
	.if n .fi
	..
	'\" # BE - end boxed text (draw box now)
	.de BE
	.nf
	.ti 0
	.mk ^t
	.ie n \l'\\n(^lu\(ul'
	.el \{\
	.\" Draw four-sided box normally, but don't draw top of
	.\" box if the box started on an earlier page.
	.ie !\\n(^b-1 \{\
	\h'-1.5n'\L'\|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'\|0u-1.5n\(ul'
	.\}
	.el \}\
	\h'-1.5n'\L'\|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'\|0u-1.5n\(ul'
	.\}
	.\}
	.fi
	.br
	.nr ^b 0
	..
	'\" # VS - start vertical sidebar
	'\" # ^Y = starting y location
	'\" # ^v = 1 (for troff; for nroff this doesn't matter)
	.de VS
	.if !"\\$2"" .br
	.mk ^Y
	.ie n 'mc \s12\(br\s0
	.el .nr ^v 1u
	..
	'\" # VE - end of vertical sidebar
	.de VE
	.ie n 'mc
	.el \{\
	.ev 2
	.nf
	.ti 0
	.mk ^t
	\h'\|\\n(^lu+3n'\L'\|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-\|\\n(^lu+3n'
	.sp -1
	.fi
	.ev
	.\}
	.nr ^v 0
	..
	'\" # Special macro to handle page bottom: finish off current
	'\" # box/sidebar if in box/sidebar mode, then invoked standard
	'\" # page bottom macro.
	.de ^B
	.ev 2
	'ti 0
	'nf
	.mk ^t
	.if \\n(^b \{\
	.\" Draw three-sided box if this is the box's first page,
	.\" draw two sides but no top otherwise.
	.ie !\\n(^b-1 \h'-1.5n'\L'\|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'\|0u'\c
	.el \h'-1.5n'\L'\|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'\|0u'\c
	.\}
	.if \\n(^v \{\
	.nr ^x \\n(^tu+1v-\\n(^Yu
	\kx\h'-\\nxu'\h'\|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'\|0u'\c
	.\}
	.bp
	'fi
	.ev
	.if \\n(^b \{\
	.mk ^y
	.nr ^b 2
	.\}
	.if \\n(^v \{\
	.mk ^Y
	.\}
	..
	'\" # DS - begin display
	.de DS
	.RS
	.nf
	.sp
	..
	'\" # DE - end display
	.de DE
	.fi
	.RE
	.sp
	..
	'\" # SO - start of list of standard options
	.de SO
	.SH "STANDARD OPTIONS"
	.LP
	.nf
	.ta 5.5c 11c
	.ft B
	..
	'\" # SE - end of list of standard options
	.de SE
	.fi
	.ft R
	.LP
	See the \\fBoptions\\fR manual entry for details on the standard options.
	..
	'\" # OP - start of full description for a single option
	.de OP
	.LP
	.nf
	.ta 4c
	Command-Line Name: \\fB\\$1\\fR
	Database Name: \\fB\\$2\\fR
	Database Class: \\fB\\$3\\fR
	.fi
	.IP
	..
	'\" # CS - begin code excerpt
	.de CS
	.RS
	.nf
	.ta .25i .5i .75i 1i
	..
	'\" # CE - end code excerpt
	.de CE
	.fi
	.RE
	..
	.de UL
	\\$1\l'\|0\(ul'\\$2
	..
	.TH send n 4.0 Tk "Tk Built-In Commands"
	.BS
	'\" Note: do not modify the .SH NAME line immediately below!
	.SH NAME
	send \- Execute a command in a different application
	.SH SYNOPSIS
	\fBsend ?\fIoptions\fR? \fIapp cmd \fR?\fIarg arg ...\fR?
	.BE

	.SH DESCRIPTION
	.PP
	This command arranges for \fIcmd\fR (and \fIarg\fRs) to be executed in the
	application named by \fIapp\fR. It returns the result or
	error from that command execution.
	\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 command to be executed is
	contained entirely within the \fIcmd\fR argument. If one or
	more \fIarg\fRs are present, they are concatenated to form the
	command to be executed, just as for the \fBeval\fR command.
	.PP
	If the initial arguments of the command begin with ``\-''
	they are treated as options. The following options are
	currently defined:
	.TP
	\fB\-async\fR
	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.
	.TP
	\fB\-displayof\fR \fIpathName\fR
	Specifies that the target application's main window is on the display
	of the window given by \fIpathName\fR, instead of the display containing
	the application's main window.
	.TP
	\fB\-\\|\-\fR
	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"
	.PP
	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
	\fBtk appname\fR command.

	.SH "DISABLING SENDS"
	.PP
	If the \fBsend\fR command is removed from an application (e.g.
	with the command \fBrename send {}\fR) then the application
	will not respond to incoming send requests anymore, nor will it
	be able to issue outgoing requests.
	Communication can be reenabled by invoking the \fBtk appname\fR
	command.

	.SH SECURITY
	.PP
	The \fBsend\fR command is potentially a serious security loophole. On Unix,
	any application that can connect to your X server can send
	scripts to your applications.
	These incoming scripts can use Tcl to read and
	write your 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, 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.
	.VS
	Under Windows, \fBsend\fR is currently disabled. Most of the
	functionality is provided by the \fBdde\fR command instead.
	.VE
	.SH KEYWORDS
	.VS
	application, dde, name, remote execution, security, send
	.VE