util/X86LINUX64/man/mann/load.n

   1 '\"
   2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
   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 .TH load n 7.5 Tcl "Tcl Built-In Commands"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .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
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 '\" Note:  do not modify the .SH NAME line immediately below!
 277 .SH NAME
 278 load \- Load machine code and initialize new commands
 279 .SH SYNOPSIS
 280 \fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName\fR
 281 .br
 282 \fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName\fR
 283 .br
 284 \fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName interp\fR
 285 .BE
 286 .SH DESCRIPTION
 287 .PP
 288 This command loads binary code from a file into the
 289 application's address space and calls an initialization procedure
 290 in the package to incorporate it into an interpreter.  \fIfileName\fR
 291 is the name of the file containing the code;  its exact form varies
 292 from system to system but on most systems it is a shared library,
 293 such as a \fB.so\fR file under Solaris or a DLL under Windows.
 294 \fIpackageName\fR is the name of the package, and is used to
 295 compute the name of an initialization procedure.
 296 \fIinterp\fR is the path name of the interpreter into which to load
 297 the package (see the \fBinterp\fR manual entry for details);
 298 if \fIinterp\fR is omitted, it defaults to the
 299 interpreter in which the \fBload\fR command was invoked.
 300 .PP
 301 Once the file has been loaded into the application's address space,
 302 one of two initialization procedures will be invoked in the new code.
 303 Typically the initialization procedure will add new commands to a
 304 Tcl interpreter.
 305 The name of the initialization procedure is determined by
 306 \fIpackageName\fR and whether or not the target interpreter
 307 is a safe one.  For normal interpreters the name of the initialization
 308 procedure will have the form \fIpkg\fB_Init\fR, where \fIpkg\fR
 309 is the same as \fIpackageName\fR except that the first letter is
 310 converted to upper case and all other letters
 311 are converted to lower case.  For example, if \fIpackageName\fR is
 312 \fBfoo\fR or \fBFOo\fR, the initialization procedure's name will
 313 be \fBFoo_Init\fR.
 314 .PP
 315 If the target interpreter is a safe interpreter, then the name
 316 of the initialization procedure will be \fIpkg\fB_SafeInit\fR
 317 instead of \fIpkg\fB_Init\fR.
 318 The \fIpkg\fB_SafeInit\fR function should be written carefully, so that it
 319 initializes the safe interpreter only with partial functionality provided
 320 by the package that is safe for use by untrusted code. For more information
 321 on Safe\-Tcl, see the \fBsafe\fR manual entry.
 322 .PP
 323 The initialization procedure must match the following prototype:
 324 .PP
 325 .CS
 326 typedef int \fBTcl_PackageInitProc\fR(
 327         Tcl_Interp *\fIinterp\fR);
 328 .CE
 329 .PP
 330 The \fIinterp\fR argument identifies the interpreter in which the
 331 package is to be loaded.  The initialization procedure must return
 332 \fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed
 333 successfully;  in the event of an error it should set the interpreter's result
 334 to point to an error message.  The result of the \fBload\fR command
 335 will be the result returned by the initialization procedure.
 336 .PP
 337 The actual loading of a file will only be done once for each \fIfileName\fR
 338 in an application.  If a given \fIfileName\fR is loaded into multiple
 339 interpreters, then the first \fBload\fR will load the code and
 340 call the initialization procedure;  subsequent \fBload\fRs will
 341 call the initialization procedure without loading the code again.
 342 For Tcl versions lower than 8.5, it is not possible to unload or reload a
 343 package. From version 8.5 however, the \fBunload\fR command allows the unloading
 344 of libraries loaded with \fBload\fR, for libraries that are aware of the
 345 Tcl's unloading mechanism.
 346 .PP
 347 The \fBload\fR command also supports packages that are statically
 348 linked with the application, if those packages have been registered
 349 by calling the \fBTcl_StaticPackage\fR procedure.
 350 If \fIfileName\fR is an empty string, then \fIpackageName\fR must
 351 be specified.
 352 .PP
 353 If \fIpackageName\fR is omitted or specified as an empty string,
 354 Tcl tries to guess the name of the package.
 355 This may be done differently on different platforms.
 356 The default guess, which is used on most UNIX platforms, is to
 357 take the last element of \fIfileName\fR, strip off the first
 358 three characters if they are \fBlib\fR, and use any following
 359 alphabetic and underline characters as the module name.
 360 For example, the command \fBload libxyz4.2.so\fR uses the module
 361 name \fBxyz\fR and the command \fBload bin/last.so {}\fR uses the
 362 module name \fBlast\fR.
 363 .PP
 364 If \fIfileName\fR is an empty string, then \fIpackageName\fR must
 365 be specified.
 366 The \fBload\fR command first searches for a statically loaded package
 367 (one that has been registered by calling the \fBTcl_StaticPackage\fR
 368 procedure) by that name; if one is found, it is used.
 369 Otherwise, the \fBload\fR command searches for a dynamically loaded
 370 package by that name, and uses it if it is found.  If several
 371 different files have been \fBload\fRed with different versions of
 372 the package, Tcl picks the file that was loaded first.
 373 .PP
 374 If \fB\-global\fR is specified preceding the filename, all symbols
 375 found in the shared library are exported for global use by other
 376 libraries. The option \fB\-lazy\fR delays the actual loading of
 377 symbols until their first actual use. The options may be abbreviated.
 378 The option \fB\-\-\fR indicates the end of the options, and should
 379 be used if you wish to use a filename which starts with \fB\-\fR
 380 and you provide a packageName to the \fBload\fR command.
 381 .PP
 382 On platforms which do not support the \fB\-global\fR or \fB\-lazy\fR
 383 options, the options still exist but have no effect. Note that use
 384 of the \fB\-global\fR or \fB\-lazy\fR option may lead to crashes
 385 in your application later (in case of symbol conflicts resp. missing
 386 symbols), which cannot be detected during the \fBload\fR. So, only
 387 use this when you know what you are doing, you will not get a nice
 388 error message when something is wrong with the loaded library.
 389 .SH "PORTABILITY ISSUES"
 390 .TP
 391 \fBWindows\fR\0\0\0\0\0
 392 .
 393 When a load fails with
 394 .QW "library not found"
 395 error, it is also possible
 396 that a dependent library was not found.  To see the dependent libraries,
 397 type
 398 .QW "dumpbin -imports <dllname>"
 399 in a DOS console to see what the library must import.
 400 When loading a DLL in the current directory, Windows will ignore
 401 .QW ./
 402 as a path specifier and use a search heuristic to find the DLL instead.
 403 To avoid this, load the DLL with:
 404 .RS
 405 .PP
 406 .CS
 407 \fBload\fR [file join [pwd] mylib.DLL]
 408 .CE
 409 .RE
 410 .SH BUGS
 411 .PP
 412 If the same file is \fBload\fRed by different \fIfileName\fRs, it will
 413 be loaded into the process's address space multiple times.  The
 414 behavior of this varies from system to system (some systems may
 415 detect the redundant loads, others may not).
 416 .SH EXAMPLE
 417 .PP
 418 The following is a minimal extension:
 419 .PP
 420 .CS
 421 #include <tcl.h>
 422 #include <stdio.h>
 423 static int fooCmd(ClientData clientData,
 424         Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) {
 425     printf("called with %d arguments\en", objc);
 426     return TCL_OK;
 427 }
 428 int Foo_Init(Tcl_Interp *interp) {
 429     if (Tcl_InitStubs(interp, "8.1", 0) == NULL) {
 430         return TCL_ERROR;
 431     }
 432     printf("creating foo command");
 433     Tcl_CreateObjCommand(interp, "foo", fooCmd, NULL, NULL);
 434     return TCL_OK;
 435 }
 436 .CE
 437 .PP
 438 When built into a shared/dynamic library with a suitable name
 439 (e.g. \fBfoo.dll\fR on Windows, \fBlibfoo.so\fR on Solaris and Linux)
 440 it can then be loaded into Tcl with the following:
 441 .PP
 442 .CS
 443 # Load the extension
 444 switch $tcl_platform(platform) {
 445     windows {
 446         \fBload\fR [file join [pwd] foo.dll]
 447     }
 448     unix {
 449         \fBload\fR [file join [pwd] libfoo[info sharedlibextension]]
 450     }
 451 }
 452
 453 # Now execute the command defined by the extension
 454 foo
 455 .CE
 456 .SH "SEE ALSO"
 457 info sharedlibextension, package(n), Tcl_StaticPackage(3), safe(n)
 458 .SH KEYWORDS
 459 binary code, dynamic library, load, safe interpreter, shared library
 460 '\"Local Variables:
 461 '\"mode: nroff
 462 '\"End: