Tcl Plugin FAQ

Please send your comments to

This FAQ is currently very outdated, see the new version reflecting the 2.0 Plugin first.

This FAQ addresses the following questions:

	0. Availability information.
	1. Running Navigator with -install makes the colors appear strange.
	2. Site wide installation - how?
	3. The Tcl plugin vs TCL_LIBRARY and TK_LIBRARY.
	4. Why can't I open a new toplevel? Why does the menu command
	   give me an error?
	5. What's a "security policy"?
	6. What's in this new file "safe.tcl"?
	7. So what can it do right now?
	8. Let me do "dangerous" things please, I know what I'm doing..
	9. I still want to do it, my site is protected by a firewall.
	10. How do I write a page containing a tclet?
	11. What is this <embed ...> statement?
	12. Environment variables vs the Tcl plugin.
	13. Installation woes.. what to check for.
	14. Sun's demos work but my pages don't -- why?
	15. My users do not have the plugin -- what to do?
	16. I want to use someone else's tclet -- how to?
	17. Dynamic loading of extensions into the plugin -- is it possible?
	18. Focus management problems..
	19. Why only a binary distribution?
	20. I want to read the sources to ensure that it's really safe..
	21. I want to get the sources to port the plugin to my platform..
	22. Why isn't the plugin available on my favorite platform?
	23. What about support for Windows 3.1?
	24. What platforms are supported now?
	25. What's the release schedule for the Tcl plugin?
	26. What bugs will be fixed by v1 final release?
	27. What new features are already planned for v2? Will there be a v3?
	28. I have a couple of machines. Can I download multiple copies of
	    the plugin, for each machine?
	29. What about commercial use?
	30. Can I redistribute the plugin? Can I bundle it on a CD ROM?
	31. I think this is cool stuff, and I want to mirror your archive.
	    How can I do that?
	32. I think this is cool stuff, and I want to help. How?
	33. I hate Tcl. Can I do a plugin with Tk for Perl, python, scheme?
	34. First Java and now Tcl? Isn't this confusing?
	35. What other information is available about the plugin? Tcl and Tk?
Here are the answers:

0. Availability information.

	The Tcl plugin is available at
	and on the Neosoft mirror site,

Back to top

1. Running Navigator with -install makes the colors of the plugin strange.

	This happens if you're using an older version of the plugin. That
	version had a bug whereby it would use its own colormap that would
	conflict with Navigator. Newer versions of the plugin (after v1a2)
	should not exhibit this problem. If you are still seeing this
	problem please email

Back to top

2. I want to do a site wide installation instead of installing in my
   home directory.

	For Unix: You can do that, but it requires a little more work than
	installing for private use. Here's how:

	- place into /usr/lib/netscape/plugins
	- place anywhere and write a shell script that
	  users will run that will set the env var NPX_PLUGIN_PATH
	  to the directory where you placed and then run
	  Netscape Navigator 3.0.


	- copy the directories tcl7.6 and tk4.2 to either
	  * /usr/lib/netscape/tclplug				OR
	  * /usr/local/lib/netscape/tclplug			OR
	  * $(NPX_PLUGIN_PATH)/../tclplug
	- copy these directories anywhere and add a line to the script
	  you wrote in the previous step to set the env var TCL_PLUGIN_DIR
	  to the directory where you copied tcl7.6 and tk4.2.

	If you wrote a script as above, publish it in a directory where
	your users will invoke it and you're done.

	NOTE: Do not place the directories tcl7.6 and tk4.2 as
	subdirectories of the directory holding, because
	Navigator will be confused by these directory (It thinks they have
	loadable modules in them instead of Tcl scripts..).

	For Windows: The plugin uses a registry key to find the Tcl
	runtime libraries, so if you installed it once, all users will be
	able to find these libraries. Just ensure that the version of
	Navigator that is shared amongst all your users has the plugin
	installed, and you're done.

	***NOTE***: Please note that a site wide installation requires
	a commercial use license if the installation will be used for
	a company related task. If each user of the site wide installation
	is using the plugin for his or her personal use, no commercial
	use license is required. Please view the answer to question 29
	below, if in doubt.

Back to top

3. I have installed the plugin and I also have another installation of
   Tcl on my machine. When I view any page containing a tclet I get a
   message saying that the file 'safe.tcl' couldn't be found. What's wrong?

	You may have the env vars TCL_LIBRARY and TK_LIBRARY set to point
	at the Tcl libraries for the other installation of Tcl on your
	machine. This confuses the plugin, preventing it from finding its
	own library. This is a known bug that is fixed in versions of the
	plugin after v1a2. A workaround is to unset these variables, and
	this should not be needed after v1a2.

Back to top

4. Why can't I open a toplevel in a Tclet? There's no menus? Can't do a
   "wm title", why? There's no "socket" command?!

	The tclet runs inside a restricted version of Tcl and Tk, called
	Safe Tk. These commands have been removed from Tcl, for safety

		cd, exec, fconfigure, file, glob, pwd, socket

	These commands have been removed from Tk, for safety reasons:

		bell, clipboard, grab, menu, send, tk, tkwait, toplevel,

	Future versions of the plugin will feature configurable security
	policies, which will let a site administrator make available a
	different set of features to a tclet.

Back to top

5. What's that, a "security policy"?

	A security policy is a list of things that a tclet can do. It is
	implemented by the master interpreter restricting the interpreter
	in which the tclet runs, so that functionality that's not in the
	specified security policy will not be accessible to the tclet. A
	master can also define new aliases (commands that when invoked in
	the tclet interpreter actually execute some code in the master)
	to provide safe access to dangerous functionality. For example,
	a master can provide an alias that allows the tclet to open a
	file for reading and writing, but only in a specified directory
	on the file system, and the file size is also limited.

	We are writing a "white paper" on Safe Tcl and how it all works.
	It will probably be posted as a Web page, and we will certainly
	make sure you hear about it once it's done. Stay tuned.

Back to top

6. What's this file "safe.tcl"?

	That's the Tcl script that implements the current (and only)
	security policy. It determines what a tclet can do.

Back to top

7. So what can it do, right now?

	First of all, check out the demos.

	These Tcl commands are available in a tclet:

		after, append, array, break, case, catch, clock, close,
		concat, continue, eof, error, eval, expr, fblocked,
		fileevent, flush, for, foreach, format, gets, global,
		history, if, incr, info, interp, join, lappend, lindex,
		linsert, list, llength, lower, lrange, lreplace, lsearch,
		lsort, package, pid, proc, puts, read, regexp, regsub,
		rename, return, scan, seek, set, split, string, subst,
		switch, tell, time, trace, unset, update, uplevel, upvar,
		unsupported0, vwait, while

	These Tk commands are available in a tclet:

		button, entry, listbox, scale, scrollbar, text, bind, .,
		focus, tkerror, bgerror, winfo, tkwait

	The safe.tcl security policy also provides these aliases:

		exit -- a safe version that only destroys the tclet.
		load -- a safe version that only loads files from a
			predetermined set of directories.
		source -- a safe version that only sources from a
			predetermined set of directories.
		open -- only allows opening files (for reading only) in
			a predetermined list of directories. A tclet can
			only have a total of four channels open at any
			one time. This increments the count and fails if
			it would go over four.
		close -- removes temporary files and decrements the count
			 of the number of files a tclet has open.
		maketmp -- makes a temporary file, limited in size to 1MB,
			opened for reading and writing. Returns the channel
			for the file. Also increments the count and fails
			if it would have gone over four.
		puts -- safe version that redirects stdout and stderr to
			Netscape's output mechanism.
		fconfigure -- only allows querying of options on channels,
			not setting them.
		dirname -- allows access to a safe subset of the
			available through dir.

Back to top

8. Come on, I know what I'm doing. Now please get out of my way and let me
   do these things you call "dangerous".

	We're sure you're a savvy person and that you know what you're
	doing, but the problem is that you can't know ahead of time what
	the script that you download from someone else's page is going
	to do. Enabling dangerous features, with the current single
	security policy, makes them available to *all* downloaded scripts.
	When we have a security framework in place (in v2), it'll be
	possible to restrict which scripts do and do not have access to
	each dangerous feature.

Back to top

9. I still want to do it. My site is isolated behind a firewall.

	We strongly advise against it anyway, because if you can visit
	pages outside the firewall, you are able to download scripts
	through the firewall. These scripts can be malicious and do bad
	things through the dangerous facilities you enabled.

	What we *can* show you how to do is to make new aliases that enable
	a tclet to use dangerous features in a safe manner. Remember that
	the master interpreter is completely unrestricted, so it still has
	all the commands (such as socket and exec) that were removed from
	the slave. What you do is write an alias target command and add an
	alias source command to the slave interprete where the tclet will
	execute. Examine the procedure tcl_makeSafe in safe.tcl for some
	examples of how to do that. For example, suppose that you wanted
	to let the tclet get the load average on the machine. You'd write:

	proc tcl_safe_uptime {} {
	    exec uptime

	and add the following line to tcl_makeSafe

	    $slave alias uptime tcl_safe_uptime

Back to top

10. How do I write a page with a tclet in it?

	Very simple. Follow these steps:

	- Write your Tcl program in a file, call it simple.tcl. The
	  important part of this is that the file has to have a '.tcl'
	  extension, because that's how Navigator decides that it is
	  a tclet.

	  For example, here is a small Hello World Tk application:

		button .b -text "Hello World" -bg red
		pack .b

	  Save the above into the simple.tcl file.

	- Write a web page (an HTML document) into a file named, e.g.,
	  simple.html, as follows:

		<title>My First Tclet</title>
		Here is my first tclet:
		<embed src=simple.tcl width=120 height=35>

	- Now visit the simple.html page with your browser, and you
	  should see the tclet, a red button with the text 'Hello World'.

Back to top

11. What is this <embed ..> statement?

	That's how Navigator finds the plugin. In it you specify:

	- the name of the source file containing the tclet, in the
	  src=... argument.
	- the width and height of the window to create to display
	  the tclet, in the width=... and height=... arguments.

	You can also invent additional name=value pairs as you wish, to
	parameterize the tclet. All the name=value pairs are made
	available to the tclet in the global array embed_args. So,
	in the example in question 10 above, embed_args would have the
	following values:
		embed_args(src) == simple.tcl
		embed_args(width) == 120
		embed_args(height) == 35

Back to top

12. I set a lot of environment variables, yet when I access env(FOO)
    in my tclet, I don't see the value I set. Why?

	Environment variables are not passed to the tclet, for security
	reasons. There is only one value that we pass, currently, and
	that is env(DISPLAY).

Back to top

13. OK, I installed the plugin and everything seems to be fine. Yet, when
    I visit any of the demos, I only get the broken image icon. Why?

	You may have the plugin installed incorrectly. Here's a quick
	list of things to check for on Unix:

	- Are you running Navigator 3.0? On Unix, only Navigator 3.0 can
	  be used to view plugins, as 2.0 does not support plugins.
	- Did you install the file in ~/.netscape/plugins?
	- Did you install the Tcl runtime libraries in ~/.tclplug?
	- Did you remember to unset TCL_LIBRARY and TK_LIBRARY in the
	  environment variables?
	- Did you remember to exit from all running instances of Navigator
	  and restart?
	- Now that you restarted Navigator, is the plugin listed as one
	  of the installed plugins in the Help->About plug-ins page? If
	  you get an empty page you may have Javascript disabled..

	On Windows:

	- Are you running Navigator 3.0 or IE 3.0? Although the plugin
	  does work with Navigator 2.0, it does not work properly with
	  2.0 Gold. We're still checking why. We strongly recommend to
	  upgrade to Navigator 3.0 as future versions of the plugin are
	  going to depend on features available only in 3.0.
	- Did you install nptcl32.dll, tk42.dll and tcl76.dll in
	- Did you install the Tcl runtime libraries in c:\tclpug?
	- Did you remember to unset TCL_LIBRARY and TK_LIBRARY in the
	  environment variables? In Windows 95, setting/unsetting env
	  vars is tricky, you probably have them set in autoexec.bat
	  or some '.ini' file..
	- Did you remember to exit from all running instances of Navigator
	  and restart?
	- Now that you restarted Navigator, is the plugin listed as one
	  of the installed plugins in the Help->About plug-ins page? If
	  you get an empty page you may have Javascript disabled..

	Now that all these questions are answered, visit our demo pages
	at and try to view
	some of the demos. Is everything working OK?

Back to top

14. Your demos work just fine, but when I visit my own pages with tclets in
    them, at, I still get the
    broken image icon. Why doesn't it work for me?

	This is likely because your web server -- the program that sends
	the pages to your browser when you click on a URL -- is not
	sending the right mime-type when it sends the '.tcl' file. You
	can work around this by adding a type=application/x-tcl name=value
	pair to the embed statement, which will cause Navigator to infer
	that it should use the Tcl plugin anyways. A better solution is
	to ask your system administrator to configure the web server to
	send the mime type application/x-tcl when it sends files with a
	'.tcl' extension. Nearly all web servers in the world nowadays
	are already configured to do this, the only ones we are aware of
	that do not are some older versions of Apache.

Back to top

15. I have users that want to visit my pages with tclets, but they do not
    have the plugin. What can I do?

	Add a pluginspage= name=value
	pair to the embed statement. This will cause Navigator to find
	the plugin for your user and suggest they install it. The user
	is then prompted to download and install the plugin, and then she
	has to restart the browser and revisit your page. Very inconvenient
	and only slightly better than giving your users the broken image
	icon. Netscape says they are working on a more automatic solution.

Back to top

16. I want to use someone else's tclet in my page. How do I do that?

	Very easy. All you have to do is to make the src=... name=value
	pair have the absolute URL for where the other person's tclet
	is stored on the net. For example, if you wanted to use the 15
	puzzle with the Java cup in your page, you'd write:

	<embed src= ...>

Back to top

17. I have a dynamically loaded extension of Tcl. How do I load it into
    the plugin?

	Right now dynamic loading into the plugin is not completely
	implemented. Eventually we will support dynamic loading completely
	and you will be able to dynamically load extensions on demand into
	the plugin with very little change to your extension. Here's what
	extension writers must do to make their extension loadable:

	* You need to implement a safe entry point. If your extension is
	  named, and your regular entry point is Foo_Init, you now
	  need to implement a second entry point, Foo_SafeInit. This
	  entry point is called with exactly the same arguments as the
	  original Foo_Init entry point.

	  Your safe entry point is responsible for only providing safe
	  functionality to the interpreter being initialized. If your
	  extension has functionality that could be used to damage the
	  integrity of the hosting system in any way, or if it could be
	  used to compromise the user's privacy of information, your
	  safe entry point should *NOT* provide that functionality to
	  the interpreter being initialized.

	Extensions that do not have a safe entry point will not be
	loaded by Tcl into a safe interpreter. Since all tclets run inside
	safe interpreters, such extensions will not be usable by tclets.

Back to top

18. Focus sometimes behaves strangely, for example, if I have a page open
   with a tclet in it, I sometimes cannot type into other windows. Why?

	This is a known bug in the current version of the plugin. We are
	working hard to improve support for focus management, but there
	are still bugs.

Back to top

19. Why are you only distributing binaries for the plugin?

	The plugin contains code that Sun believes is of high value. At
	this time Sun is not releasing the source code, but in the future
	that may change. We are considering restricted source licenses.
	Contact Jacob Levy ( if you believe you have a
	need for the source code.

	However, we also believe that for most uses source code will not
	be needed. When the plugin fully supports dynamic loading, it will
	not be necessary to extend it through source modification at all.

Back to top

20. I'm a security expert for my site. My boss won't let me run the plugin
    until I tell him it's safe to do so. So, I want to read the sources so
    that I can convince myself it's really safe.

	Contact us. We are open to doing special releases of the sources
	for this purpose. You will be required to sign a license that will
	prohibit any use of the sources other than for the express purpose
	of examining them for security risks.

Back to top

21. I want the sources so I can port the plugin to my favorite platform.

	Thanks for the interest. Please contact us and we can talk about
	it. You will probably be required to sign a special license that
	will go over all the issues.

Back to top

22. The plugin is not available for my favorite platform. How come?

	We will make the plugin available on all platforms that
	qualify as follows:

	- Navigator supports plugins on that platform.
	- There is sufficient demand for a Tcl plugin on that platform.

	We can determine the second of these by hearing about it from
	you. Please do the homework and find out before asking if Navigator
	does or doesn's support plugins on your platform. If it doesn't
	there is nothing we can do; in that case you may wish to contact
	Netscape to inform them of your interest.

Back to top

23. OK, but what about a Windows 3.1 release? There's millions of these
    boxes out there...

	Yes, we know there are millions of these boxes out there :). We
	are examining what it would take to run the plugin on Windows 3.1.
	If it's possible, it'll be a priority goal for v2.

Back to top

24. What platforms does it run on now?

	The plugin runs on Windows 95, Windows NT 3.5x, Windows NT 4.0,
	with Netscape Navigator 2.02, Navigator 3.0, Navigator Gold 3.0 and
	Microsoft Internet Explorer 3.0. To use the plugin under Microsoft
	Internet Explorer 3.0 you currently also have to have Netscape
	Navigator installed -- Microsoft assures me that they're working
	real hard to fix that problem :).

	The plugin works on MacOS 7 on both 68K and PowerPC.

	The plugin works on the following versions of Unix:

	- Solaris 2.4 and up, both on Sparc and X86 machines.
	- SunOS 4.1.4 and up, on Sparc machines.
	- IRIX 5.3, on SGI machines.
	- Linux 1.x and Linux 2.0.7; there are conflicting reports about
	  whether it works on Linux 2.0.10 and higher.
	- HPUX 9.x and HPUX 10.x.
	- OSF 1 may or may not become supported before v1 ships.

Back to top

25. What's the release schedule for the plugin?

	We're in the final stages of releasing v1 now. The release is
	feature complete, and it runs on all the platforms that v1 is
	intended to run on. We hope to make a final v1 release before
	the end of September '96.

	We're also planning what features will go into v2, right now.
	If you have a feature that you want to see in v2, please let
	us know, by email, at

	The release schedule for v2 will start immediately once we are
	done with v1. Expect to see the first alpha sometime in October
	of '96.

Back to top

26. What bugs from the above mentioned will still be fixed in v1?

	V1 will no longer have the colormap problem, and it will no longer
	be necessary to unset TCL_LIBRARY and TK_LIBRARY. We do not know
	at present whether we will be able to completely address the focus
	problems, and dynamic loading will likely still be only supported

Back to top

27. What are you already planning to put into v2? Is there going to be a v3?

	First, we plan to make v2 have a security framework, so you'll be
	able to have more than one security policy. Tclets will be able to
	ask the plugin to run them under a different policy than the default
	policy. We will also provide several new interesting security
	policies that enable different features than the default policy, to
	demonstrate that different policies are possible and interesting.

	Second, we plan to add the ability for the tclet to communicate
	with Navigator and with Java applets and Javascript scripts in the
	same page. For example, we'll add a way for the tclet to get a new
	stream that will make the contents of a file identified by a URL
	available to the tclet, and we'll make it possible for a tclet to
	send data to Navigator through a URL. We'll also make it possible
	for a tclet to set and query other elements in a page, for example
	it'll be possible to read form entry fields or to set their values.

	We also plan to make it possible for a tclet to contact the host
	from which it was loaded. Yes, we do know how to prevent the DNS
	spoofing attack.. :)

	All of these features will be accessible to the	tclet only if it is
 	running under a security policy that enables this; we do not plan to
	make any of this accessible through the default policy.

	Finally, we may be able to provide hooks into authentication
	mechanisms, so that a tclet can ask for a security policy that
	requires trusting the writer of the tclet. Using authentication it
	will then be possible to determine that the tclet was written by
	someone the user trusts, and to then let it have access to really
	dangerous facilities such as exec, if the user trusts the author of
	the tclet sufficiently.

	There is likely to be a v3, and a v4, etc. Depends on what features
	people want. We already know we won't be able to do everything we
	want to do with the plugin in v2.

	We're also working on embedding Tcl and Tk into other frameworks
	besides plugins. Watch for Tcl and Tk to become available as OLE
	controls (ActiveX components), as OpenDoc parts, etc. This is all
	futuristic stuff, no schedule yet.

Back to top

28. I have more than one machine, perhaps with different OSes. Can I
    download more than one copy of the plugin?

	Yes, go ahead. The license says that you can use the plugin for
	private use in an unrestricted manner, and you can obtain one
	copy for your private use.

	If your company has many employees and you do not know who else
	downloaded the plugin, don't worry. You are not in violation of
	our license for at least ninety days.

Back to top

29. Can I use the plugin commercially?

	Yes, sure. You just have to contact Sun to obtain a commercial
	license. The commercial license will not be free. You need to
	obtain a commercial license if you're employed by a company and
	you want to use the plugin for a company related task after the
	ninety day evaluation period expires. If you are an employee of
	a company and want to use the plugin for personal use only, you
	do not need to obtain such a license.

Back to top

30. Can I redistribute the plugin? Can I bundle it for example on a CD ROM?

	The license states that redistribution and bundling are expressly
	prohibited. If you do want to do this, contact Sun and we can
	consider your request.

Back to top

31. This is cool stuff, I want to help by mirroring the archive.

	Please contact us. Thanks for the offer! We have one mirror already
	set up at For mirroring to work,
	you need to be willing to respond quickly when we release a new
	version, to upgrade your site also.

Back to top

32. This is way cool! How can I help?

	Thanks for the kind words. You can help in the following ways:

	- write more tclets and let us know about them so we can link
	  to your pages. Write a killer app!
	- make your pages have links to the Sun Labs site.
	- tell your friends, and teach them how easy it is to write tclets.
	- write articles and letters to the editors of some of the major
	  PC related magazines.

Back to top

33. I hate Tcl, but I think Tk is cool. Can I create a Perl or Python
    plugin that uses Tk?

	First, we're sorry you hate Tcl :). It's not so bad, really..
	Of course we're happy that you like Tk. We also think it's
	way cool!

	Second, there are already plugins for Perl and Python. You can
	find them on the web.

	Third, the version of Tk that the Tcl plugin uses (Tk 4.3) is not
	yet released. This version supports embedding of Tk applications
	inside other applications (e.g. Navigator). Once that version is
	released, you could use it to do what the Tcl plugin does. I can't
	comment on when the Tk 4.3 release cycle might start, sorry. We're
	in Beta for Tk 4.2 now, so a bit more patience might help.

Back to top

34. I thought you guys were into Java. What's this Tcl stuff.. Isn't it

	We don't think it is confusing. Yes, we love Java. We intend for
	the plugin to be able to talk to Java and Javascript, real soon.
	Sun is fully committed to making Java the best it can be. A lot of
	resources are going into making Java *the* natural choice for any
	system programming task you might undertake in the near future.

	Realistically, however, Java is not the solution to all the world's
	problems just like C++ was not. There are tasks for which you do
	not want to use Java, medium and small sized programs. Just like
	you wrote some of your code in C/C++ and some in csh or awk or sed,
	you can now do some of your work on the web in Java, and some other
	parts are more a suitable in Tcl and Tk. We believe that where
	computational efficiency really matters, you want to use Java (e.g.
	doing joins on databases) but when you just want to display
	something quickly, Tk is better.

	For our complete position statement on the relationship between
	Java and Tcl please visit

Back to top

35. What other information is available about the plugin? About Tcl and Tk?

	The Sun Labs web site is the primary resource. Visit the Tcl plugin
	pages at

	This site has all the up to date information about the plugin, and
	it will also point at where to obtain the "white paper" once we've
	finished writing it.

	There are many sites on the web that provide information about
	Tcl. The primary Sun site is at Other
	important sites are the Tcl Resource Mirror site at Neosoft, Inc.,
	at Yahoo has pointers to about 100
	other Tcl related sites, visit

	There is a wealth of published material about Tcl and more is
	being written all the time. We are aware of a book being written
	that will cover tclet programming specifically, and there are
	chapters about the Tcl plugin in several other books whose subject
	is plugins in general. The FAQ about published materials on Tcl
	is available at 

	It is being maintained by Glenn Vanderburg (

Thanks to Peter Ruczynski for producing the initial HTML-ized version of the plugin FAQ.

Back to top

Tcl top | Overview | TclRCX | Tcl Plug-in | Apps.& Ext. | More Links

Last modified: Mon May 04 2009, 14:09, hosted by