'\"
'\" Copyright (c) 1995-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.
'\"
.so man.macros
.TH Tcl_InitSubsystems 3 8.6.1 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_InitSubsystems \- initialize the Tcl library.
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Interp *
\fBTcl_InitSubsystems\fR(\fIflags\fR, \fI...\fR)
.SH ARGUMENTS
.AS int flags
.AP int flags in
Any combination of flags which indicate whether a custom panicProc
is registered and/or a real interpreter is created.
The value 0 can be used if Tcl is used as utility library only.
.BE
.SH DESCRIPTION
.PP
The \fBTcl_InitSubsystems\fR procedure initializes the Tcl
library. This procedure is typically invoked as the very
first thing in the application's main program.
Its \fBflags\fR argument controls exactly what is initialized,
and what additional arguments are expected.
.PP
The call \fBTcl_InitSubsystems(0)\fR does the same as
\fBTcl_FindExecutable(NULL)\fR, except that a Tcl_Interp *
is returned which can be used only by \fBTcl_InitStubs\fR
to initialize the stub table. This opens up the Tcl Stub
technology for Tcl embedders, which now can dynamically
load the Tcl shared library and use functions in it
without ever creating an interpreter. E.g. the
following code can be compiled with -DUSE_TCL_STUBS:
.CS
Tcl_Interp *interp, *(*initSubSystems)(int, ...);
const char *version;
void *handle = dlopen("libtcl8.6.so", RTLD_NOW|RTLD_LOCAL);
initSubSystems = dlsym(handle, "Tcl_InitSubsystems");
version = Tcl_InitStubs(initSubSystems(0), NULL, 0);
/* At this point, Tcl C API calls without interp are ready for use */
interp = Tcl_CreateInterp(); /* Now we have a real interpreter */
Tcl_InitStubs(interp, version, 0); /* Initialize the stub table again */
.CE
This is equivalent to (without dynamical loading)
.CS
Tcl_Interp *interp;
const char *version;
version = Tcl_InitStubs(Tcl_InitSubSystems(0), NULL, 0);
/* At this point, Tcl C API calls without interp are ready for use */
interp = Tcl_CreateInterp(); /* Now we have a real interpreter */
Tcl_InitStubs(interp, version, 0); /* Initialize the stub table again */
.CE
The function \fBTcl_CreateInterp\fR, or any other Tcl function you
would like to call, no longer needs to be searched for in the
shared library. It can be called directly through the stub table.
Note that the stub table needs to be initialized twice, in order
to be sure that you can call all functions without limitations
after the real interpreter is created.
.PP
If you supply the flag \fBTCL_INIT_PANIC\fR to \fBTcl_InitSubsystems\fR,
the function expects an additional argument, a custom panicProc.
This is equivalent to calling \fBTcl_SetPanicProc\fR immediately
before \fBTcl_InitSubsystems\fR, except that you possibly cannot do
that yet if it requires an initialized stub table. Of course you
could call \fBTcl_SetPanicProc\fR immediately after \fBTcl_InitSubsystems\fR,
but then panics which could be produced by the initialization
itself still use the default panic procedure.
.PP
If you supply one of the flags \fBTCL_INIT_CREATE\fR, \fBTCL_INIT_CREATE_UTF8\fR or
\fBTCL_INIT_CREATE_UNICODE\fR to \fBTcl_InitSubsystems\fR, the function
gets two additional parameters, argc and argv. Then a real
Tcl interpreter will be created. If argc > 0 then the variables
\fBargc\fR and \fBargv\fR will be set in this interpreter. The 3
variants assume a different encoding for the arguments, except for
\fIargv[0]\fR which is always assumed to be in the system encoding.
So, the above example code could be simplified to:
.CS
Tcl_Interp *interp = Tcl_InitSubSystems(TCL_INIT_CREATE, 0, NULL);
Tcl_InitStubs(interp, TCL_VERSION, 0); /* initialize the stub table */
.CE
.PP
If the \fBTCL_INIT_PANIC\fR and one of the \fBTCL_INIT_CREATE\fR
flags are used in combination, the \fBpanicProc\fR argument comes
before the argc/argv arguments.
.PP
The reason for \fBargv[0]\fR always using the system encoding is that this way,
argv[0] can be derived directly from the main() (or mainw, on Windows)
arguments without any processing. \fBTCL_INIT_CREATE_UNICODE\fR is really only
useful on Windows. But on Windows, the argv[0] parameter is not used for
determining the value of [info executable] anyway. Modern UNIX system already
have UTF-8 as system encoding, so \fBTCL_INIT_CREATE_UTF8\fR would have the same
effect as \fBTCL_INIT_CREATE\fR, only slightly faster. Other parameters can be
preprocessed at will by the application, and if the application uses unicode
or UTF-8 internally there is no need to convert it back to the system encoding.
.PP
The interpreter returned by Tcl_InitSubsystems(0) cannot be passed to
any other function than Tcl_InitStubs(). Tcl functions with an "interp"
argument can only be called if the function supports passing NULL.
.SH KEYWORDS
binary, executable file