1 | '\" |
---|
2 | '\" Copyright (c) 2003 George Petasis <petasis@iit.demokritos.gr>. |
---|
3 | '\" |
---|
4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
6 | '\" |
---|
7 | '\" RCS: @(#) $Id: unload.n,v 1.11 2008/03/26 14:51:42 dkf Exp $ |
---|
8 | '\" |
---|
9 | .so man.macros |
---|
10 | .TH unload n 8.5 Tcl "Tcl Built-In Commands" |
---|
11 | .BS |
---|
12 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
13 | .SH NAME |
---|
14 | unload \- Unload machine code |
---|
15 | .SH SYNOPSIS |
---|
16 | \fBunload \fR?\fIswitches\fR? \fIfileName\fR |
---|
17 | .br |
---|
18 | \fBunload \fR?\fIswitches\fR? \fIfileName packageName\fR |
---|
19 | .br |
---|
20 | \fBunload \fR?\fIswitches\fR? \fIfileName packageName interp\fR |
---|
21 | .BE |
---|
22 | .SH DESCRIPTION |
---|
23 | .PP |
---|
24 | This command tries to unload shared libraries previously loaded |
---|
25 | with \fBload\fR from the application's address space. \fIfileName\fR |
---|
26 | is the name of the file containing the library file to be unload; it |
---|
27 | must be the same as the filename provided to \fBload\fR for |
---|
28 | loading the library. |
---|
29 | The \fIpackageName\fR argument is the name of the package (as |
---|
30 | determined by or passed to \fBload\fR), and is used to |
---|
31 | compute the name of the unload procedure; if not supplied, it is |
---|
32 | computed from \fIfileName\fR in the same manner as \fBload\fR. |
---|
33 | The \fIinterp\fR argument is the path name of the interpreter from |
---|
34 | which to unload the package (see the \fBinterp\fR manual entry for |
---|
35 | details); if \fIinterp\fR is omitted, it defaults to the |
---|
36 | interpreter in which the \fBunload\fR command was invoked. |
---|
37 | .PP |
---|
38 | If the initial arguments to \fBunload\fR start with \fB\-\fR then |
---|
39 | they are treated as switches. The following switches are |
---|
40 | currently supported: |
---|
41 | .TP |
---|
42 | \fB\-nocomplain\fR |
---|
43 | . |
---|
44 | Suppresses all error messages. If this switch is given, \fBunload\fR will |
---|
45 | never report an error. |
---|
46 | .TP |
---|
47 | \fB\-keeplibrary\fR |
---|
48 | . |
---|
49 | This switch will prevent \fBunload\fR from issuing the operating system call |
---|
50 | that will unload the library from the process. |
---|
51 | .TP |
---|
52 | \fB\-\|\-\fR |
---|
53 | . |
---|
54 | Marks the end of switches. The argument following this one will |
---|
55 | be treated as a \fIfileName\fR even if it starts with a \fB\-\fR. |
---|
56 | .SS "UNLOAD OPERATION" |
---|
57 | .PP |
---|
58 | When a file containing a shared library is loaded through the |
---|
59 | \fBload\fR command, Tcl associates two reference counts to the library |
---|
60 | file. The first counter shows how many times the library has been |
---|
61 | loaded into normal (trusted) interpreters while the second describes how many |
---|
62 | times the library has been loaded into safe interpreters. As a file containing |
---|
63 | a shared library can be loaded only once by Tcl (with the first \fBload\fR |
---|
64 | call on the file), these counters track how many interpreters use the library. |
---|
65 | Each subsequent call to \fBload\fR after the first simply increments the |
---|
66 | proper reference count. |
---|
67 | .PP |
---|
68 | \fBunload\fR works in the opposite direction. As a first step, \fBunload\fR |
---|
69 | will check whether the library is unloadable: an unloadable library exports |
---|
70 | a special unload procedure. The name of the unload procedure is determined by |
---|
71 | \fIpackageName\fR and whether or not the target interpreter |
---|
72 | is a safe one. For normal interpreters the name of the initialization |
---|
73 | procedure will have the form \fIpkg\fB_Unload\fR, where \fIpkg\fR |
---|
74 | is the same as \fIpackageName\fR except that the first letter is |
---|
75 | converted to upper case and all other letters |
---|
76 | are converted to lower case. For example, if \fIpackageName\fR is |
---|
77 | \fBfoo\fR or \fBFOo\fR, the initialization procedure's name will |
---|
78 | be \fBFoo_Unload\fR. |
---|
79 | If the target interpreter is a safe interpreter, then the name |
---|
80 | of the initialization procedure will be \fIpkg\fB_SafeUnload\fR |
---|
81 | instead of \fIpkg\fB_Unload\fR. |
---|
82 | .PP |
---|
83 | If \fBunload\fR determines that a library is not unloadable (or unload |
---|
84 | functionality has been disabled during compilation), an error will be returned. |
---|
85 | If the library is unloadable, then \fBunload\fR will call the unload |
---|
86 | procedure. If the unload procedure returns \fBTCL_OK\fR, \fBunload\fR will proceed |
---|
87 | and decrease the proper reference count (depending on the target interpreter |
---|
88 | type). When both reference counts have reached 0, the library will be |
---|
89 | detached from the process. |
---|
90 | .SS "UNLOAD HOOK PROTOTYPE" |
---|
91 | .PP |
---|
92 | The unload procedure must match the following prototype: |
---|
93 | .CS |
---|
94 | typedef int Tcl_PackageUnloadProc(Tcl_Interp *\fIinterp\fR, int \fIflags\fR); |
---|
95 | .CE |
---|
96 | .PP |
---|
97 | The \fIinterp\fR argument identifies the interpreter from which the |
---|
98 | library is to be unloaded. The unload procedure must return |
---|
99 | \fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed |
---|
100 | successfully; in the event of an error it should set the interpreter's result |
---|
101 | to point to an error message. In this case, the result of the |
---|
102 | \fBunload\fR command will be the result returned by the unload procedure. |
---|
103 | .PP |
---|
104 | The \fIflags\fR argument can be either \fBTCL_UNLOAD_DETACH_FROM_INTERPRETER\fR |
---|
105 | or \fBTCL_UNLOAD_DETACH_FROM_PROCESS\fR. In case the library will remain |
---|
106 | attached to the process after the unload procedure returns (i.e. because |
---|
107 | the library is used by other interpreters), |
---|
108 | \fBTCL_UNLOAD_DETACH_FROM_INTERPRETER\fR will be defined. However, if the |
---|
109 | library is used only by the target interpreter and the library will be |
---|
110 | detached from the application as soon as the unload procedure returns, |
---|
111 | the \fIflags\fR argument will be set to \fBTCL_UNLOAD_DETACH_FROM_PROCESS\fR. |
---|
112 | .SS NOTES |
---|
113 | .PP |
---|
114 | The \fBunload\fR command cannot unload libraries that are statically |
---|
115 | linked with the application. |
---|
116 | If \fIfileName\fR is an empty string, then the \fIpackageName\fR argument must |
---|
117 | be specified. |
---|
118 | .PP |
---|
119 | If \fIpackageName\fR is omitted or specified as an empty string, |
---|
120 | Tcl tries to guess the name of the package. |
---|
121 | This may be done differently on different platforms. |
---|
122 | The default guess, which is used on most UNIX platforms, is to |
---|
123 | take the last element of \fIfileName\fR, strip off the first |
---|
124 | three characters if they are \fBlib\fR, and use any following |
---|
125 | alphabetic and underline characters as the module name. |
---|
126 | For example, the command \fBunload libxyz4.2.so\fR uses the module |
---|
127 | name \fBxyz\fR and the command \fBunload bin/last.so {}\fR uses the |
---|
128 | module name \fBlast\fR. |
---|
129 | .SH "PORTABILITY ISSUES" |
---|
130 | .TP |
---|
131 | \fBUnix\fR\0\0\0\0\0 |
---|
132 | . |
---|
133 | Not all unix operating systems support library unloading. Under such |
---|
134 | an operating system \fBunload\fR returns an error (unless \fB\-nocomplain\fR |
---|
135 | has been specified). |
---|
136 | .SH BUGS |
---|
137 | .PP |
---|
138 | If the same file is \fBload\fRed by different \fIfileName\fRs, it will |
---|
139 | be loaded into the process's address space multiple times. The |
---|
140 | behavior of this varies from system to system (some systems may |
---|
141 | detect the redundant loads, others may not). In case a library has been |
---|
142 | silently detached by the operating system (and as a result Tcl thinks the |
---|
143 | library is still loaded), it may be dangerous to use |
---|
144 | \fBunload\fR on such a library (as the library will be completely detached |
---|
145 | from the application while some interpreters will continue to use it). |
---|
146 | .SH EXAMPLE |
---|
147 | If an unloadable module in the file \fBfoobar.dll\fR had been loaded |
---|
148 | using the \fBload\fR command like this (on Windows): |
---|
149 | .CS |
---|
150 | load c:/some/dir/foobar.dll |
---|
151 | .CE |
---|
152 | then it would be unloaded like this: |
---|
153 | .CS |
---|
154 | \fBunload\fR c:/some/dir/foobar.dll |
---|
155 | .CE |
---|
156 | .PP |
---|
157 | This allows a C code module to be installed temporarily into a |
---|
158 | long-running Tcl program and then removed again (either because it is |
---|
159 | no longer needed or because it is being updated with a new version) |
---|
160 | without having to shut down the overall Tcl process. |
---|
161 | .SH "SEE ALSO" |
---|
162 | info sharedlibextension, load(n), safe(n) |
---|
163 | .SH KEYWORDS |
---|
164 | binary code, unloading, safe interpreter, shared library |
---|