[25] | 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 |
---|