1TclX(TCL)                                                            TclX(TCL)
2
3
4

NAME

6       TclX - Extended Tcl: Extended command set for Tcl
7

SYNOPSIS

9       package require Tclx
10

INTRODUCTION

12       This man page contains the documentation for all of the extensions that
13       are added to Tcl by Extended Tcl (TclX).  TclX extends Tcl's  capabili‐
14       ties by adding new commands to it, without changing the syntax of stan‐
15       dard Tcl.  Extended Tcl is a superset of  standard  Tcl  and  is  built
16       alongside the standard Tcl sources.
17
18       Extended  Tcl  was  created by Karl Lehenbauer and Mark Diekhans and is
19       freely redistributable for any use without license or fee.
20
21       Available since 1989, Extended Tcl, also known as TclX, not  only  adds
22       capabilities  to Tcl, but has also been the source of many of the capa‐
23       bilities of the baseline Tcl release, including arrays, files, sockets,
24       file events, and date and time handling, among others.
25
26       Extended  Tcl  introduces  a  set of new commands and a user-extensible
27       library of useful Tcl procedures, any of  which  can  be  automatically
28       loaded on the first attempt to execute it.
29
30       The command descriptions are separated into several sections:
31
32            · General Commands
33
34            · Debugging and Development Commands
35
36            · Unix Access Commands
37
38            · File Commands
39
40            · Network Programming Support
41
42            · File Scanning Commands
43
44            · Math Commands
45
46            · List Manipulation Commands
47
48            · Keyed Lists
49
50            · String and Character Manipulation Commands
51
52            · XPG/3 Message Catalog Commands
53
54            · Help Facility
55
56            · Tcl Loadable Libraries and Packages
57

GENERAL COMMANDS

59       A  set  of general, useful Tcl commands, includes a command to begin an
60       interactive session with Tcl, a facility for tracing execution,  and  a
61       looping command.
62
63       dirs   This procedure lists the directories in the directory stack.
64
65       commandloop  ?-async?  ?-interactive  on  |  off  | tty? ?-prompt1 cmd?
66       ?-prompt2 cmd? ?-endcommand cmd?
67
68              Create an interactive command loop reading commands  from  stdin
69              and  writing  results to stdout.  Command loops are maybe either
70              be blocking or event oriented.  This command is useful  for  Tcl
71              scripts  that do not normally converse interactively with a user
72              through a Tcl command interpreter, but which sometimes  want  to
73              enter  this  mode,  perhaps for debugging or user configuration.
74              The command loop terminates on EOF.
75
76              The following options are available:
77
78              -async A command handler will be associated  with  stdin.   When
79                     input  is available on stdin, it will be read and accumu‐
80                     lated until a full command is  available.   That  command
81                     will  then  be  evaluated.  An event loop must be entered
82                     for input to be read and processed.
83
84              -interactive on | off | tty
85                     Enable or disable interactive command mode.  In  interac‐
86                     tive  mode,  commands are prompted for and the results of
87                     comments are printed.  The value maybe any boolean  value
88                     or  tty.   If tty is used, interactive mode is enabled if
89                     stdin is associated with a terminal or terminal emulator.
90                     The default is tty.
91
92              -prompt1 cmd
93                     If  specified,  cmd   is  used is evaluate and its result
94                     used for the main command prompt.  If not specified,  the
95                     command in tcl_prompt1 is evaluated to output the prompt.
96                     Note the difference in behavior,  cmd  results  is  used,
97                     while  tcl_prompt1  outputs.  This is to allow for future
98                     expansion to command loops that write to other than  std‐
99                     out.
100
101              -prompt2 cmd
102                     If specified, cmd is used is evaluate and its result used
103                     for the secondary (continuation) command prompt.  If  not
104                     specified,  the  command  in  tcl_prompt2 is evaluated to
105                     output the prompt.
106
107              -endcommand cmd
108                     If specified, cmd is evaluated when the command loop ter‐
109                     minates.
110
111                     In interactive mode, the results of set commands with two
112                     arguments are not printed.
113
114                     If SIGINT is configured to generate a Tcl error,  it  can
115                     be  used to delete the current command being type without
116                     aborting the program in progress.
117
118       echo ?str ...?
119              Writes zero or more strings to standard output,  followed  by  a
120              newline.
121
122       infox option
123
124              Return  information  about Extended Tcl, or the current applica‐
125              tion.  The following infox command options are available:
126
127              version
128                     Return the version number of Extended Tcl.   The  version
129                     number  for  Extended  Tcl  is generated by combining the
130                     base version of the standard Tcl code with another number
131                     indicating the version of Extended Tcl being used.
132
133              patchlevel
134                     Return the patchlevel for Extended Tcl.
135
136              have_fchown
137                     Return  1  if  the fchown system call is available.  This
138                     supports the -fileid option on the chown and  chgrp  com‐
139                     mands.
140
141              have_fchmod
142                     Return  1  if  the fchmod system call is available.  This
143                     supports the -fileid option on the chmod command.
144
145              have_flock
146                     Return 1 if the flock command defined,  0 if  it  is  not
147                     available.
148
149              have_fsync
150                     Return  1  if  the fsync system call is available and the
151                     sync command will sync individual files.  0 if it is  not
152                     available  and the sync command will always sync all file
153                     buffers.
154
155              have_ftruncate
156                     Return 1 if the ftruncate or chsize system call is avail‐
157                     able.   If  it  is,  the ftruncate command -fileid option
158                     maybe used.
159
160              have_msgcats
161                     Return 1 if XPG message catalogs are available, 0 if they
162                     are not.  The catgets is designed to continue to function
163                     without message catalogs, always  returning  the  default
164                     string.
165
166              have_posix_signals
167                     Return  1  if  Posix  signals  are  available  (block and
168                     unblock options available for the signal command).  0  is
169                     returned if Posix signals are not available.
170
171              have_signal_restart
172                     Return  1  if restartable signals are available (-restart
173                     option available for the signal command).  0 is  returned
174                     if restartable signals are not available.
175
176              have_truncate
177                     Return 1 if the truncate system call is available.  If it
178                     is, the ftruncate command may truncate by file path.
179
180              have_waitpid
181                     Return 1 if the waitpid system call is available and  the
182                     wait  command has full functionality.  0 if the wait com‐
183                     mand has limited functionality.
184
185              appname
186                     Return the  symbolic  application  name  of  the  current
187                     application  linked with the Extended Tcl library.  The C
188                     variable tclAppName must be set  by  the  application  to
189                     return an application specific value for this variable.
190
191              applongname
192                     Return  a  natural language name for the current applica‐
193                     tion. The C variable tclLongAppName must be  set  by  the
194                     application  to  return an application specific value for
195                     this variable.
196
197              appversion
198                     Return the version number for  the  current  application.
199                     The  C variable tclAppVersion must be set by the applica‐
200                     tion to return an  application-specific  value  for  this
201                     variable.
202
203              apppatchlevel
204                     Return the patchlevel for the current application.  The C
205                     variable tclAppPatchlevel must be set by the  application
206                     to  return  an  application-specific value for this vari‐
207                     able.
208
209       for_array_keys var array_name code
210              This procedure performs a foreach-style loop for each key in the
211              named  array.   The  break  and continue statements work as with
212              foreach.
213
214       for_recursive_glob var dirlist globlist code
215              This procedure performs a foreach-style  loop  over  recursively
216              matched  files.   All  directories  in  dirlist  are recursively
217              searched (breadth-first), comparing each file found against  the
218              file  glob  patterns  in  globlist.   For each matched file, the
219              variable var is set to the file  path  and  code  is  evaluated.
220              Symbolic links are not followed.
221
222       loop var first limit ?increment? body
223              Loop  is  a  looping command, similar in behavior to the Tcl for
224              statement, except that the loop statement achieves substantially
225              higher  performance and is easier to code when the beginning and
226              ending values of a loop are known, and the loop variable  is  to
227              be  incremented  by a known, fixed amount every time through the
228              loop.
229
230               The var argument is the name of a Tcl variable that  will  con‐
231              tain  the loop index.  The loop index is set to the value speci‐
232              fied by first.  The Tcl interpreter is invoked upon body zero or
233              more  times,  where  var  is incremented by increment every time
234              through the loop, or by  one  if  increment  is  not  specified.
235              Increment  can  be  negative  in  which case the loop will count
236              downwards.
237
238              When var reaches limit, the loop terminates without a subsequent
239              execution  of  body.  For instance, if the original loop parame‐
240              ters would cause loop to terminate, say first was one, limit was
241              zero  and  increment was not specified or was non-negative, body
242              is not executed at all and loop returns.
243
244              The first, limit and increment are  integer  expressions.   They
245              are only evaluated once at the beginning of the loop.
246
247              If  a continue command is invoked within body then any remaining
248              commands in the current execution of body are skipped, as in the
249              for command.  If a break command is invoked within body then the
250              loop command will return immediately.   Loop  returns  an  empty
251              string.
252
253       popd   This  procedure  pops the top directory entry from the directory
254              stack and make it the current directory.
255
256       pushd ?dir?
257              This procedure pushes the current directory onto  the  directory
258              stack  and  cd  to the specified directory.  If the directory is
259              not specified, then the current directory is pushed, but remains
260              unchanged.
261
262       recursive_glob dirlist globlist
263              This procedure returns a list of recursively matches files.  All
264              directories in dirlist are recursively searched (breadth-first),
265              comparing  each  file  found  against  the file glob patterns in
266              globlist.  Symbolic links are not followed.
267
268       showproc ?procname ...?
269              This procedure lists the definition  of  the  named  procedures.
270              Loading them if it is not already loaded.  If no procedure names
271              are supplied, the definitions of all currently loaded procedures
272              are returned.
273
274       try_eval code catch ?finally?
275              The try_eval command evaluates code in the current context.
276
277       If  an  error occurs during the evaluation and catch is not empty, then
278       catch is evaluated to handler the error.  The result  of  the  command,
279       containing  the  error  message,  will  be  stored in a global variable
280       errorResult.  The global variables errorResult, errorInfo and errorCode
281       will  be imported into the current scope, there is no need to execute a
282       global command.  The result of the catch command becomes the result  of
283       the  try_eval command.  If the error that caused the catch to be evalu‐
284       ate is to be continued, the following command should be used:
285            error $errorResult $errorCode $errorInfo
286
287       If the finally argument is supplied and  not  empty,  it  is  evaluated
288       after  the  evaluation of the code and the catch commands.  If an error
289       occurs during the evaluation of the finally  command,  it  becomes  the
290       result  of  the try_eval command.  Otherwise, the result of either code
291       or catch is preserved, as described above.
292

DEBUGGING AND DEVELOPMENT COMMANDS

294       This section contains information on commands and procedures  that  are
295       useful for developing and debugging Tcl scripts.
296
297
298       cmdtrace  level  |  on  ?noeval? ?notruncate? ?procs? ?fileid? ?command
299       cmd?
300
301              Print a trace statement for all commands executed  at  depth  of
302              level  or  below  (1 is the top level).  If on is specified, all
303              commands at any level are traced.   The  following  options  are
304              available:
305
306              noeval Causes arguments to be printed unevaluated.  If noeval is
307                     specified, the arguments are printed  before  evaluation.
308                     Otherwise, they are printed afterwards.
309
310                     If  the  command line is longer than 60 characters, it is
311                     truncated to 60 and a "..."  is  postpended  to  indicate
312                     that  there  was  more  output than was displayed.  If an
313                     evaluated argument contains a space, the entire  argument
314                     will  be  enclosed  inside  of braces (`{}') to allow the
315                     reader to  visually  separate  the  arguments  from  each
316                     other.
317
318              notruncate
319                     Disables  the  truncation of commands and evaluated argu‐
320                     ments.
321
322              procs  Enables the tracing of procedure  calls  only.   Commands
323                     that  aren't procedure calls (i.e. calls to commands that
324                     are written in C, C++ or some object-compatible language)
325                     are  not  traced  if the procs option is specified.  This
326                     option is particularly useful for  greatly  reducing  the
327                     output of cmdtrace while debugging.
328
329              fileid This  is  a  file id as returned by the open command.  If
330                     specified, then the trace output will be written  to  the
331                     file  rather  than  stdout.  A stdio buffer flush is done
332                     after every line is written so that the trace may be mon‐
333                     itored  externally  or  provide  useful  information  for
334                     debugging problems that cause core dumps.
335
336              command cmd
337
338                     Call the specified command cmd on when  each  command  is
339                     executed  instead of tracing to a file.  See the descrip‐
340                     tion of the functionally below.  This option may  not  be
341                     specified with a fileid.
342
343              The  most  common  use of this command is to enable tracing to a
344              file during the development.  If a failure occurs,  a  trace  is
345              then  available when needed.  Command tracing will slow down the
346              execution of  code,  so  it  should  be  removed  when  code  is
347              debugged.   The  following command will enable tracing to a file
348              for the remainder of the program:
349
350                   cmdtrace on [open cmd.log w]
351
352              The command option causes a user specified trace command  to  be
353              called  for  each  command  executed.  The command will have the
354              following arguments appended to it before evaluation:
355
356              command
357                     A string containing the text of the command,  before  any
358                     argument substitution.
359
360              argv   A  list  of  the  final argument information that will be
361                     passed to the command after command, variable, and  back‐
362                     slash substitution.
363
364              evalLevel
365                     The Tcl_Eval call level.
366
367              procLevel
368                     The procedure call level.
369
370              The  command should be constructed in such a manner that it will
371              work if additional arguments are added in  the  future.   It  is
372              suggested  that  the  command  be a proc with the final argument
373              being args.
374
375              Tracing will be turned off while the command is being  executed.
376              The  values  of  the  errorInfo  and errorCode variables will be
377              saved and restored on return from the command.  It is  the  com‐
378              mand's responsibility to preserve all other state.
379
380              If  an  error  occurs  during the execution of command, an error
381              message is dumped to stderr and the tracing  is  disabled.   The
382              underlying  mechanism  that  this functionality is built on does
383              not support returning an error to the interpreter.
384
385       cmdtrace off
386              Turn off all tracing.
387
388       cmdtrace depth
389              Returns the current maximum trace level, or  zero  if  trace  is
390              disabled.
391
392       edprocs ?proc...?
393              This  procedure  writes  the  named procedures, or all currently
394              defined procedures, to a temporary file, then calls an editor on
395              it  (as  specified  by the EDITOR environment variable, or vi if
396              none is specified), then sources the file  back  in  if  it  was
397              changed.
398
399       profile ?-commands? ?-eval? on
400
401       profile off arrayVar
402              This  command  is used to collect a performance profile of a Tcl
403              script.  It collects data at the Tcl procedure level. The number
404              of  calls to a procedure, and the amount of real and CPU time is
405              collected. Time is also collected for the global  context.   The
406              procedure  data is collected by bucketing it based on the proce‐
407              dure call stack, this allows determination of how much  time  is
408              spent  in  a  particular  procedure in each of it's calling con‐
409              texts.
410
411              The on option enables profile data collection. If the  -commands
412              option  is specified, data on all commands within a procedure is
413              collected as well a procedures.  Multiple occurrences of a  com‐
414              mand within a procedure are not distinguished, but this data may
415              still be useful for analysis.
416
417              The off option turns off profiling and moves the data  collected
418              to  the array arrayVar.  The array is address by a list contain‐
419              ing the procedure call stack.  Element zero is the  top  of  the
420              stack,  the  procedure  that  the data is for.  The data in each
421              entry is a list consisting of the procedure call count  and  the
422              real  time  and  CPU time in milliseconds spent in the procedure
423              (but not any procedures it calls).  The  list  is  in  the  form
424              {count real cpu}.
425
426              Normally,  the  variable  scope stack is used in reporting where
427              time is spent.  Thus upleveled code is reported in  the  context
428              that  it  was  executed in, not the context that the uplevel was
429              called in.  If the -eval  option  is  specified,  the  procedure
430              evaluation  (call)  stack is used instead of the procedure scope
431              stack.  Upleveled code is reported in the context of the  proce‐
432              dure that did the uplevel.
433
434              A  Tcl  procedure  profrep is supplied for reducing the data and
435              producing a report.
436
437              On Windows, profile command only reports elapsed real time,  CPU
438              time is not available and is reported as zero.
439
440       profrep profDataVar sortKey ?outFile? ?userTitle?
441              This  procedure  generates  a  report from data collect from the
442              profile command.  ProfDataVar is the name of the array  contain‐
443              ing  the data returned by the profile command. SortKey indicates
444              which data value to sort by.  It should be one of "calls", "cpu"
445              or  "real".  OutFile is the name of file to write the report to.
446              If omitted, stdout is assumed.  UserTitle is an  optional  title
447              line to add to output.
448
449              Listed  with  indentation below each procedure or command is the
450              procedure call stack.  The first indented line being the  proce‐
451              dure  that  invoked the reported procedure or command.  The next
452              line is the procedure that invoked the procedure above  it,  and
453              so  on.   If  no indented procedures are shown, the procedure or
454              command was called from the global context.  Time actually spent
455              in  the  global  context  is  listed on a line labeled <global>.
456              Upleveled code is reported in the context that it  was  executed
457              in, not the context that the uplevel was called in.
458
459       saveprocs fileName ?proc...?
460              This  procedure  saves the definition of the named procedure, or
461              all currently defined procedures if none is  specified,  to  the
462              named file.
463

UNIX ACCESS COMMANDS

465       These  commands provide access to many basic Unix facilities, including
466       process handling, date and time processing,  signal  handling  and  the
467       executing commands via the shell.
468
469       alarm seconds
470              Instructs  the  system to send a SIGALRM signal in the specified
471              number of seconds.  This is a floating point  number,  so  frac‐
472              tions  of  a  section  may be specified.  If seconds is 0.0, any
473              previous alarm request is canceled.  Only one alarm  at  a  time
474              may be active; the command returns the number of seconds left in
475              the previous alarm.  On systems  without  the  setitimer  system
476              call, seconds is rounded up to an integer number of seconds.
477
478              The alarm command is not available on Windows.
479
480       execl ?-argv0 argv0? prog ?arglist?
481              Do  an execl, replacing the current program (either Extended Tcl
482              or an application with Extended Tcl embedded into it) with  prog
483              and passing the arguments in the list arglist.
484
485              The  -argv0  options specifies that argv0 is to be passed to the
486              program as argv [0] rather than prog.
487
488              Note: If you are using execl in a Tk application and  it  fails,
489              you  may  not do anything that accesses the X server or you will
490              receive a BadWindow error from the X server.  This includes exe‐
491              cuting the Tk version of the exit command.  We suggest using the
492              following command to abort Tk applications after an execl  fail‐
493              ure:
494
495                  kill [id process]
496
497              On  Windows,  where  the  fork  command  is not available, execl
498              starts a new process and returns the process id.
499
500       chroot dirname
501              Change  root  directory  to  dirname,  by  invoking  the   POSIX
502              chroot(2) system call.  This command only succeeds if running as
503              root.
504
505       fork   Fork the current Tcl process.  Fork returns zero  to  the  child
506              process  and  the  process  number  of  the  child to the parent
507              process.  If the fork fails, a Tcl error is generated.
508
509              If an execl is not  going  to  be  performed  before  the  child
510              process  does output, or if a close and dup sequence is going to
511              be performed on stdout or stderr, then a flush should be  issued
512              against  stdout,  stderr  and  any other open output file before
513              doing the fork. Otherwise characters  from  the  parent  process
514              pending  in  the  buffers  will be output by both the parent and
515              child processes.
516
517              Note: If you are forking in a  Tk  based  application  you  must
518              execl  before  doing  any  window operations in the child or you
519              will receive a BadWindow error from the X server.
520
521              The fork command is not available on Windows.
522
523       id options
524
525              This command provides a means of getting, setting and converting
526              user,  group  and process ids.  The id command has the following
527              options:
528
529              id user ?name?
530
531              id userid ?uid?
532                     Set the real and effective user ID to name or uid, if the
533                     name  (or uid) is valid and permissions allow it.  If the
534                     name (or uid) is not specified, the current name (or uid)
535                     is returned.
536
537              id convert userid uid
538
539              id convert user name
540                     Convert a user ID number to a user name, or vice versa.
541
542              id group ?name?
543
544              id groupid ?gid?
545                     Set  the  real  and effective group ID to name or gid, if
546                     the name (or gid) is valid and permissions allow it.   If
547                     the  group  name  (or  gid) is not specified, the current
548                     group name (or gid) is returned.
549
550              id groups
551
552              id groupids
553                     Return the current group access list of the process.  The
554                     option groups returns group names and groupids returns id
555                     numbers.
556
557              id convert groupid gid
558
559              id convert group name
560                     Convert a group ID number to a group name, or vice versa.
561
562              id effective user
563
564              id effective userid
565                     Return the effective user name, or effective user ID num‐
566                     ber, respectively.
567
568              id effective group
569
570              id effective groupid
571                     Return  the  effective  group name, or effective group ID
572                     number, respectively.
573
574              id effective groupids
575                     Return all of the groupids the user is a member of.
576
577              id host
578                     Return the hostname of the system the program is  running
579                     on.
580
581              id process
582                     Return the process ID of the current process.
583
584              id process parent
585                     Return  the  process  ID  of  the  parent  of the current
586                     process.
587
588              id process group
589                     Return the process group ID of the current process.
590
591              id process group set
592                     Set the process group ID of the current  process  to  its
593                     process ID.
594
595              id host
596                     Returns the standard host name of the machine the process
597                     is executing on.
598
599                     On Windows, only the host and process options are  imple‐
600                     mented.
601
602       kill ?-pgroup ?signal? idlist
603
604              Send a signal to the each process in the list idlist, if permit‐
605              ted.  Signal, if present, is the signal number or  the  symbolic
606              name of the signal, see the signal system call manual page.  The
607              leading ``SIG'' is optional when the signal is specified by  its
608              symbolic name.  The default for signo is 15, SIGTERM.
609
610              If  -pgroup  is  specified,  the  numbers  in idlist are take as
611              process group ids and the signal is sent to all of  the  process
612              in  that  process  group.  A process group id of 0 specifies the
613              current process group.
614
615              On Windows,  the  kill  command  is  capable  of  terminating  a
616              process, but not of sending an arbitrary signal.
617
618       link ?-sym? srcpath destpath
619
620              Create  a  directory entry, destpath, linking it to the existing
621              file, srcpath.  If -sym is specified, a  symbolic  link,  rather
622              than  a  hard link, is created.  (The -sym option is only avail‐
623              able on systems that support symbolic links.)
624
625              The link command is not available on Windows.  Use the Tcl  8.4+
626              file link command instead.
627
628       nice ?priorityincr?
629
630              Change or return the process priority.  If priorityincr is omit‐
631              ted, the current priority is returned.  If priorityincr is posi‐
632              tive,  it is added to the current priority level, up to a system
633              defined maximum (normally 19),
634
635              Negative priorityincr values cumulatively increase the program's
636              priority  down  to  a  system  defined  minimum  (normally -19);
637              increasing priority with negative niceness values will only work
638              for the superuser.
639
640              The new priority is returned.
641
642              The nice command is not available on Windows.
643
644       readdir ?-hidden? dirPath
645
646              Returns a list containing the contents of the directory dirPath.
647              The directory entries "." and ".." are not returned.
648
649              On Windows, -hidden maybe specified to include hidden  files  in
650              the result.  This flag is ignored on Unix systems.
651
652       signal ?-restart? action siglist ?command?
653
654              Warning:   If  signals are being used as an event source (a trap
655              action), rather than generating an error to  terminate  a  task;
656              one  must use the -restart option.  This causes a blocked system
657              call, such as read or waitpid to be restarted rather than gener‐
658              ate  an  error.   Failure  to  do this may results in unexpected
659              errors when a signal arrives while in one of these system calls.
660              When available, the -restart option can prevent this problem.
661
662              If  -restart  is specified, restart blocking system calls rather
663              than generating an error.  The signal will be handled  once  the
664              Tcl command that issued the system call completes.  The -restart
665              options is not available on all operating systems  and  its  use
666              will  generate  an  error  when  it is not supported.  Use infox
667              have_signal_restart to check for availability.
668
669              Specify the action to take when a Unix  signal  is  received  by
670              Extended Tcl, or a program that embeds it.  Siglist is a list of
671              either the symbolic or numeric Unix signal (the  SIG  prefix  is
672              optional).   Action  is  one of the following actions to be per‐
673              formed on receipt of the signal.  To specify all modifiable sig‐
674              nals,  use  `*'  (this  will not include SIGKILL and SIGSTOP, as
675              they can not be modified).
676
677              default
678                     Perform system default action  when  signal  is  received
679                     (see signal system call documentation).
680
681              ignore Ignore the signal.
682
683              error  Generate  a  catchable  Tcl  error.  It will be as if the
684                     command that was running returned an  error.   The  error
685                     code will be in the form:
686                          POSIX SIG signame
687                     For  the  death  of  child signal, signame will always be
688                     SIGCHLD, rather than SIGCLD, to  allow  writing  portable
689                     code.
690
691              trap   When the signal occurs, execute command and continue exe‐
692                     cution if an error is not returned by command.  The  com‐
693                     mand will be executed in the global context.  The command
694                     will be edited before execution, replacing occurrences of
695                     "%S" with the signal name.  Occurrences of "%%" result in
696                     a single "%".  This editing occurs just before  the  trap
697                     command is evaluated.  If an error is returned, then fol‐
698                     low the standard Tcl error mechanism.  Often command will
699                     just do an exit.
700
701              get    Retrieve  the  current settings of the specified signals.
702                     A keyed list will be returned were the keys  are  one  of
703                     the  specified signals and the values are a list consist‐
704                     ing of the action associated with the signal, a 0 if  the
705                     signal  may  be  delivered  (not  block) and a 1 if it is
706                     blocked and a flag indicating  if  restarting  of  system
707                     calls   is   specified.    The   actions   maybe  one  of
708                     `default',`ignore', `error' or `trap'.  If the action  is
709                     trap,  the  third  element is the command associated with
710                     the action.  The action `unknown' is returned if  a  non-
711                     Tcl signal handler has been associated with the signal.
712
713              set    Set  signals  from a keyed list in the format returned by
714                     the get.  For this action, siglist is the keyed  list  of
715                     signal  state.   Signals  with an action of `unknown' are
716                     not modified.
717
718              block  Block the specified signals from being  received.  (Posix
719                     systems only).
720
721              unblock
722                     Allow  the  specified signal to be received. Pending sig‐
723                     nals will not occur. (Posix systems only).
724
725              The signal action will remain enabled after the specified signal
726              has occurred.  The exception to this is SIGCHLD on systems with‐
727              out Posix signals.  For these systems, SIGCHLD is not  be  auto‐
728              matically reenabled.  After a SIGCHLD signal is received, a call
729              to wait must be performed to retrieve the  exit  status  of  the
730              child process before issuing another signal SIGCHLD ... command.
731              For code that is to be portable between both types  of  systems,
732              use this approach.
733
734              Signals  are not processed until after the completion of the Tcl
735              command that is executing when the signal is  received.   If  an
736              interactive Tcl shell is running, then the SIGINT will be set to
737              error, non-interactive Tcl sessions leave SIGINT unchanged  from
738              when  the  process started (normally default for foreground pro‐
739              cesses and ignore for processes in the background).
740
741       sleep seconds
742              Sleep the Extended Tcl process for seconds seconds.  Seconds, if
743              specified as a decimal number, is truncated to an integer value.
744
745       system cmdstr1 ?cmdstr2...?
746              Concatenates   cmdstr1,   cmdstr2 etc with space separators (see
747              the concat command) into a single command and then evaluates the
748              command  using the standard system shell.  On Unix systems, this
749              is /bin/sh and on Windows its command.com.  The exit code of the
750              command is returned.
751
752              This  command  differs  from  the  exec  command  in that system
753              doesn't return the executed command's  standard  output  as  the
754              result string, and system goes through the Unix shell to provide
755              wild card expansion, redirection, etc, as is normal from  an  sh
756              command line.
757
758       sync ?fileId?
759
760              If fileId is not specified, or if it is and this system does not
761              support the fsync system call, issues  a  sync  system  call  to
762              flush  all  pending disk output.  If fileId is specified and the
763              system does support the fsync system call, issues  an  fsync  on
764              the  file corresponding to the specified Tcl fileId to force all
765              pending output to that file out to the disk.
766
767              If fileId is specified, the file must be writable.  A flush will
768              be issued against the fileId before the sync.
769
770              The  infox  have_fsync command can be used to determine if "sync
771              fileId" will do a sync or a fsync.
772
773       times
774              Return a list containing the process and child  execution  times
775              in the form:
776                   utime stime cutime cstime
777              Also  see  the times(2) system call manual page.  The values are
778              in milliseconds.
779
780       umask ?octalmask?
781              Sets file-creation mode mask to the octal  value  of  octalmask.
782              If octalmask is omitted, the current mask is returned.
783
784       wait ?-nohang? ?-untraced? ?-pgroup? ?pid?
785              Waits for a process created with the execl command to terminate,
786              either due to an untrapped signal or call to exit  system  call.
787              If  the  process id pid is specified, they wait on that process,
788              otherwise wait on any child process to terminate.
789
790              If -nohang is specified, then don't block waiting on  a  process
791              to terminate.  If no process is immediately available, return an
792              empty list.  If -untraced is specified then the status of  child
793              processes  that  are  stopped, and whose status has not yet been
794              reported since they stopped, are also returned.  If  -pgroup  is
795              specified  and  pid  is  not  specified,  then wait on any child
796              process whose process group ID  is  they  same  as  the  calling
797              process.  If pid is specified with -pgroup, then it is take as a
798              process group ID, waiting on any process in that  process  group
799              to terminate.
800
801              Wait returns a list containing three elements: The first element
802              is the process id  of  the  process  that  terminated.   If  the
803              process  exited  normally, the second element is `EXIT', and the
804              third contains the numeric exit code.  If the process terminated
805              due to a signal, the second element is `SIG', and the third con‐
806              tains the signal name.  If the process is currently stopped  (on
807              systems that support SIGSTP), the second element is `STOP', fol‐
808              lowed by the signal name.
809
810              Note that it is possible to wait on processes to terminate  that
811              were  create  in the background with the exec command.  However,
812              if any other exec command is executed after the  process  termi‐
813              nates,  then  the process status will be reaped by the exec com‐
814              mand and will not be available to the wait command.
815
816              On  systems  without  the  waitpid  system  call,  the  -nohang,
817              -untraced  and  -pgroup  options  are  not available.  The infox
818              have_waitpid command maybe use to determine if this  functional‐
819              ity is available.
820

FILE COMMANDS

822       These  commands  provide  extended  file access and manipulation.  This
823       includes searching ASCII-sorted data files, copying files,  duplicating
824       file  descriptors, control of file access options, retrieving open file
825       status, and creating pipes with the pipe  system  call.   Also  linking
826       files, setting file, process, and user attributes and truncating files.
827       An interface to the select system call is  available  on  Unix  systems
828       that support it.
829
830       It should be noted that Tcl file I/O is implemented on top of the stdio
831       library.  By default, the file is buffered.  When  communicating  to  a
832       process  through  a pipe, a flush command should be issued to force the
833       data out.  Alternatively, the fcntl command may  be  used  to  set  the
834       buffering mode of a file to line-buffered or unbuffered.
835
836       bsearch fileId key ?retvar? ?compare_proc?
837              Search  an  opened  file  fileId containing lines of text sorted
838              into ascending order for a match.  Key contains  the  string  to
839              match.   If  retvar is specified, then the line from the file is
840              returned in retvar, and the command returns 1 if key was  found,
841              and  0  if  it  wasn't.  If retvar is not specified or is a null
842              name, then the command returns the line that was  found,  or  an
843              empty string if key wasn't found.
844
845              By  default,  the  key  is matched against the first white-space
846              separated field in each line.  The field is treated as an  ASCII
847              string.   If compare_proc is specified, then it defines the name
848              of a Tcl procedure to evaluate against each line read  from  the
849              sorted  file  during the execution of the bsearch command.  Com‐
850              pare_proc takes two arguments, the key and a line extracted from
851              the  file.  The compare routine should return a number less than
852              zero if the key is less than the line, zero if the  key  matches
853              the  line,  or  greater than zero if the key is greater than the
854              line.  The file must be sorted in ascending order  according  to
855              the  same criteria compare_proc uses to compare the key with the
856              line, or erroneous results will occur.
857
858              This command does not  work  on  files  containing  binary  data
859              (bytes of zero).
860
861       chmod [-fileid] mode filelist
862              Set  permissions  of  each  of the files in the list filelist to
863              mode, where mode is an absolute numeric mode or symbolic permis‐
864              sions  as  in  the  UNIX chmod(1) command.  To specify a mode as
865              octal, it should be prefixed with a "0" (e.g. 0622).
866
867              If the option -fileid is specified, filelist is a list  of  open
868              file  identifiers rather than a list of file names.  This option
869              is not available on all Unix systems.  Use the infox have_fchmod
870              command to determine if this functionality is available.
871
872              The chmod command is not available on Windows.
873
874       chown [-fileid] owner | {owner group} filelist
875              Set  owner of each file in the list filelist to owner, which can
876              be a user name or numeric user id.  If the first parameter is  a
877              list, then the owner is set to the first element of the list and
878              the group is set to the second element.  Group can  be  a  group
879              name  or  numeric group id.  If group is {}, then the file group
880              will be set to the login group of the specified user.
881
882              If the option -fileid is specified, filelist is a list  of  open
883              file  identifiers rather than a list of file names.  This option
884              is not available on all Unix systems.  Use the infox have_fchown
885              command to determine if this functionality is available.
886
887              The chown command is not available on Windows.
888
889       chgrp [-fileid] group filelist
890              Set  the  group  id  of each file in the list filelist to group,
891              which can be either a group name or a numeric group id.
892
893              If the option -fileid is specified, filelist is a list  of  open
894              file  identifiers rather than a list of file names.  This option
895              is not available on all Unix systems.  Use the infox have_fchown
896              command to determine if this functionality is available.
897
898              The chgrp command is not available on Windows.
899
900       dup fileId ?targetFileId?
901              Duplicate  an open file.  A new file id is opened that addresses
902              the same file as fileId.
903
904              If targetFileId is specified, the the file is dup to this speci‐
905              fied  file  id.  Normally this is stdin, stdout, or stderr.  The
906              dup command will handle flushing output and closing  this  file.
907              The  new  file  will be buffered, if its needs to be unbuffered,
908              use the fcntl command to set it unbuffered.
909
910              If fileId is a number rather than a Tcl file id,  then  the  dup
911              command  will  bind  that file to a Tcl file id.  This is useful
912              for accessing files that are passed  from  the  parent  process.
913              The argument ?targetFileId? is not valid with this operation.
914
915              On  Windows,  only stdin, stdout, or stderr or a non-socket file
916              handle number maybe specified for targetFileId.  The dup command
917              does not work on sockets on Windows.
918
919       fcntl fileId attribute ?value?
920              This  command either sets or clears a file option or returns its
921              current value.  If value is  not  specified,  then  the  current
922              value  of  attribute  is returned.  All values are boolean. Some
923              attributes maybe only be gotten, not  modified.   The  following
924              attributes may be specified:
925
926       RDONLY The file is opened for reading only. (Get only)
927
928       WRONLY The file is opened for writing only.  (Get only)
929
930       RDWR   The file is opened for reading and writing.  (Get only)
931
932       READ   If the file is readable. (Get only).
933
934       WRITE  If the file is writable. (Get only).
935
936       APPEND The  file  is opened for append-only writes.  All writes will be
937              forced to the end of the file. (Get or set).
938
939       NONBLOCK
940              The file is to be accessed with non-blocking I/O.  See the  read
941              system  call for a description of how it affects the behavior of
942              file reads.
943
944       CLOEXEC
945              Close the file on an process exec.  If the execl command or some
946              other  mechanism causes the process to do an exec, the file will
947              be closed if this option is set.
948
949       NOBUF  The file is not buffered. If set, then there  no  buffering  for
950              the file.
951
952       LINEBUF
953              Output  the  file  will  be  line  buffered.  The buffer will be
954              flushed when a newline is written, when the buffer is  full,  or
955              when input is requested.
956
957       KEEPALIVE
958              Keep  a socket connection alive.  If SIGPIPE is enabled, then it
959              is sent if connection is broken  and  data  is  written  to  the
960              socket.   If  SIGPIPE  is  ignored,  an error is returned on the
961              write.  This attribute is valid only on  sockets.   By  default,
962              SIGPIPE is ignored in Tcl.
963
964              The  NONBLOCK,  NOBUF and LINEBUF are provided for compatibility
965              with older scripts.  Thefconfigure command is  preferred  method
966              of getting and setting these attributes.
967
968              The APPEND and CLOEXEC options are not available on Windows.
969
970       flock options fileId ?start? ?length? ?origin?
971
972              This  command places a lock on all or part of the file specified
973              by fileId.  The lock is either advisory or mandatory,  depending
974              on  the  mode bits of the file.  The lock is placed beginning at
975              relative byte offset start for length bytes.  If start or length
976              is  omitted  or empty, zero is assumed.  If length is zero, then
977              the lock always extents to end of file, even if the file  grows.
978              If  origin is "start", then the offset is relative to the begin‐
979              ning of the file. If it is "current", it is relative to the cur‐
980              rent  access  position  in the file.  If it is "end", then it is
981              relative to the end-of-file (a negative is before the EOF, posi‐
982              tive is after).  If origin is omitted, start is assumed.
983
984              The following options are recognized:
985
986              -read  Place a read lock on the file.  Multiple processes may be
987                     accessing the file with read-locks.
988
989              -write Place a write lock on the file.  Only one process may  be
990                     accessing a file if there is a write lock.
991
992              -nowait
993                     If specified, then the process will not block if the lock
994                     can not be  obtained.   With  this  option,  the  command
995                     returns 1 if the lock is obtained and 0 if it is not.
996
997              See  your  system's  fcntl  system  call  documentation for full
998              details of the behavior of file locking.  If  locking  is  being
999              done  on  ranges  of  a  file, it is best to use unbuffered file
1000              access (see the fcntl command).
1001
1002              The flock command is not available on Windows 95.  It is  avail‐
1003              able on Windows NT.
1004
1005       for_file var filename code
1006              This  procedure  implements  a loop over the contents of a file.
1007              For each line in filename, it sets var to the line and  executes
1008              code.
1009
1010              The break and continue commands work as with foreach.
1011
1012              For example, the command
1013
1014                   for_file line /etc/passwd {echo $line}
1015
1016              would echo all the lines in the password file.
1017
1018       funlock fileId ?start? ?length? ?origin?
1019              Remove  a locked from a file that was previously placed with the
1020              flock command.  The arguments are the same as for the flock com‐
1021              mand, see that command for more details.
1022
1023              The  funlock  command  is  not  available  on Windows 95.  It is
1024              available on Windows NT.
1025
1026       fstat fileId ?item? | ?stat arrayvar?
1027
1028              Obtain status information about an open file.
1029
1030              The following keys are used to identify data items:
1031
1032              atime  The time of last access.
1033
1034              ctime  The time of last file status change
1035
1036              dev    The device containing a directory  for  the  file.   This
1037                     value  uniquely  identifies the file system that contains
1038                     the file.
1039
1040              gid    The group ID of the file's group.
1041
1042              ino    The inode number.  This  field  uniquely  identifies  the
1043                     file in a given file system.
1044
1045              mode   The mode of the file (see the mknod system call).
1046
1047              mtime  Time when the data in the file was last modified.
1048
1049              nlink  The number of links to the file.
1050
1051              size   The file size in bytes.
1052
1053              tty    If  the file is associated with a terminal, then 1 other‐
1054                     wise 0.
1055
1056              type   The type of the file in symbolic form, which  is  one  of
1057                     the  following values: file, directory, characterSpecial,
1058                     blockSpecial, fifo, link, or socket.
1059
1060              uid    The user ID of the file's owner.
1061
1062              If one of these keys is specified as item, then that  data  item
1063              is returned.
1064
1065              If  stat arrayvar is specified, then the information is returned
1066              in the array arrayvar.  Each of the above keys indexes  an  ele‐
1067              ment of the array containing the data.
1068
1069              If  only  fileId is specified, the command returns the data as a
1070              keyed list.
1071
1072              The following values may be returned only  if  explicitly  asked
1073              for, it will not be returned with the array or keyed list forms:
1074
1075              remotehost
1076                     If  fileId  is a TCP/IP socket connection, then a list is
1077                     returned with the first element being the remote host  IP
1078                     address.   If  the  remote  host name can be found, it is
1079                     returned as the second element of the list.   The  remote
1080                     host IP port number is the third element.
1081
1082              localhost
1083                     If  fileId  is a TCP/IP socket connection, then a list is
1084                     returned with the first element being the local  host  IP
1085                     address.   If  the  local  host  name can be found, it is
1086                     returned as the second element of the  list.   The  local
1087                     host IP port number is the third element.
1088
1089       ftruncate [-fileid] file newsize
1090              Truncate a file to have a length of at most newsize bytes.
1091
1092              If the option -fileid is specified, file is an open file identi‐
1093              fier, otherwise it is a file path.
1094
1095              This command is not available or not  fully  functional  if  the
1096              underlying  operating system support is not available.  The com‐
1097              mand infox have_truncate will indicate if this command may trun‐
1098              cate  by file path.  The command infox have_ftruncate will indi‐
1099              cate if this command may truncate by file id.
1100
1101              The -fileid option is not available on Windows.
1102
1103       lgets fileId ?varName?
1104              Reads the next Tcl list from the file given by fileId  and  dis‐
1105              cards  the  terminating newline character.  This command differs
1106              from the gets command, in that it reads Tcl  lists  rather  than
1107              lines.   If the list contains newlines or binary data, then that
1108              newline or bytes of zero will be returned as part of the result.
1109              Only  a newline not quoted as part of the list indicates the end
1110              of the list.  There is no corresponding command  for  outputting
1111              lists, as puts will do this correctly.
1112
1113              If varName is specified, then the line is placed in the variable
1114              by that name and the return value is a count of  the  number  of
1115              characters  read (not including the newline).  If the end of the
1116              file is  reached  before  reading  any  characters  then  -1  is
1117              returned  and  varName is set to an empty string.  If varName is
1118              specified and an error occurs, what ever data was read  will  be
1119              returned  in  the variable, however the resulting string may not
1120              be a valid list.
1121
1122              If varName is not specified then the return value  will  be  the
1123              line (minus the newline character) or an empty string if the end
1124              of the file is reached before reading any characters.  An  empty
1125              string  will  also  be returned if a line contains no characters
1126              except the newline, so eof may have to be used to determine what
1127              really happened.
1128
1129              The  lgets command maybe used to read and write lists containing
1130              binary data, however translation must be set to lf or  the  data
1131              maybe corrupted.
1132
1133              If lgets is currently supported on non-blocking files.
1134
1135       pipe ?fileId_var_r fileId_var_w?
1136              Create  a pipe.  If fileId_var_r and fileId_var_r are specified,
1137              then pipe will set the a variable named fileId_var_r to  contain
1138              the  fileId of the side of the pipe that was opened for reading,
1139              and fileId_var_w will contain the fileId of the side of the pipe
1140              that was opened for writing.
1141
1142              If  the fileId variables are not specified, then a list contain‐
1143              ing the read and write fileIdw is returned as the result of  the
1144              command.
1145
1146       read_file ?-nonewline? fileName
1147
1148       read_file fileName numBytes
1149              This  procedure reads the file fileName and returns the contents
1150              as a string.  If -nonewline is specified, then the last  charac‐
1151              ter  of  the  file  is discarded if it is a newline.  The second
1152              form specifies exactly how many bytes will be read and returned,
1153              unless  there are fewer than numBytes bytes left in the file; in
1154              this case, all the remaining bytes are returned.
1155
1156       select readfileIds ?writefileIds? ?exceptfileIds? ?timeout?
1157              This command allows an Extended Tcl program to wait on  zero  or
1158              more  files being ready for for reading, writing, have an excep‐
1159              tional condition pending, or for a  timeout  period  to  expire.
1160              readFileIds,  writeFileIds,  exceptFileIds  are  each  lists  of
1161              fileIds, as returned from open, to query.  An  empty  list  ({})
1162              may be specified if a category is not used.
1163
1164              The  files  specified by the readFileIds list are checked to see
1165              if data is available for reading. The writeFileIds  are  checked
1166              if the specified files are clear for writing.  The exceptFileIds
1167              are checked to see if  an  exceptional  condition  has  occurred
1168              (typically, an error).  The write and exception checking is most
1169              useful on devices, however, the read  checking  is  very  useful
1170              when   communicating  with  multiple  processes  through  pipes.
1171              Select considers data pending in the stdio input buffer for read
1172              files  as being ready for reading, the files do.  not have to be
1173              unbuffered.
1174
1175              Timeout is a floating point timeout value, in  seconds.   If  an
1176              empty  list  is  supplied (or the parameter is omitted), then no
1177              timeout is set.  If the value is zero, then the  select  command
1178              functions  as a poll of the files, returning immediately even if
1179              none are ready.
1180
1181              If the timeout period expires with none of  the  files  becoming
1182              ready,  then  the  command returns an empty list.  Otherwise the
1183              command returns a list of three elements, each of those elements
1184              is  a  list of the fileIds that are ready in the read, write and
1185              exception classes.  If none are ready in a class, then that ele‐
1186              ment will be the null list.  For example:
1187
1188                      select {file3 file4 file5} {file6 file7} {} 10.5
1189
1190              could return
1191
1192                      {file3 file4} {file6} {}
1193
1194              or perhaps
1195
1196                      file3 {} {}
1197
1198              On  Windows,  only  sockets can be used with the select command.
1199              Pipes, as returned by the open command, are not supported.
1200
1201       write_file fileName string ?string...?
1202              This procedure writes the specified strings to the named file.
1203

NETWORK PROGRAMMING SUPPORT

1205       TclX provides functionality to complement the Tcl socket command.   The
1206       host_info command is used to get information about a host by name or IP
1207       address.  In addition, the fstat and fcntl commands provide options  of
1208       querying and controlling connected sockets.  To obtain the host name of
1209       the system the local system, use the id host command.
1210
1211       host_info option host
1212              Obtain information about an Internet host. The argument host can
1213              be either a host name or an IP address.
1214
1215              The following subcommands are recognized:
1216
1217              addresses
1218                     Return the list of IP addresses for host.
1219
1220              official_name
1221                     Return official name for host.
1222
1223              aliases
1224                     Return  the  list  of aliases for host.  (Note that these
1225                     are IP number aliases, not DNS CNAME aliases. See  ifcon‐
1226                     fig(2).)
1227

FILE SCANNING COMMANDS

1229       These  commands provide a facility to scan files, matching lines of the
1230       file against regular expressions and executing Tcl  code  on  a  match.
1231       With  this  facility  you can use Tcl to do the sort of file processing
1232       that is traditionally done with awk.  And since Tcl's approach is  more
1233       declarative,  some of the scripts that can be rather difficult to write
1234       in awk are simple to code in Tcl.
1235
1236       File scanning in Tcl centers around the concept of a scan  context.   A
1237       scan  context  contains  one  or more match statements, which associate
1238       regular expressions to scan for with Tcl code to be executed  when  the
1239       expressions are matched.
1240
1241       scancontext ?option?
1242              This  command  manages  file scan contexts.  A scan context is a
1243              collection of regular expressions and commands to  execute  when
1244              that  regular  expression matches a line of the file.  A context
1245              may also have a single default  match,  to  be  applied  against
1246              lines  that do not match any of the regular expressions.  Multi‐
1247              ple scan contexts may be defined and they may be reused on  mul‐
1248              tiple  files.  A scan context is identified by a context handle.
1249              The scancontext command takes the following forms:
1250
1251       scancontext create
1252              Create a new scan context.  The scanmatch  command  is  used  to
1253              define  patterns  in  the context.  A contexthandle is returned,
1254              which the Tcl programmer uses to refer to the newly created scan
1255              context in calls to the Tcl file scanning commands.
1256
1257       scancontext delete contexthandle
1258              Delete  the  scan  context identified by contexthandle, and free
1259              all of the match statements  and  compiled  regular  expressions
1260              associated with the specified context.
1261
1262       scancontext copyfile contexthandle ?filehandle?
1263              Set  or  return  the file handle that unmatched lines are copied
1264              to.  (See scanfile).  If filehandle is omitted,  the  copy  file
1265              handle is returned.  If no copy file is associated with the con‐
1266              text, {} is returned.  If a file handle is specified, it becomes
1267              the  copy  file  for this context.  If filehandle is {}, then it
1268              removes any copy file specification for the context.
1269
1270       scanfile ?-copyfile copyFileId? contexthandle fileId
1271              Scan the file specified by fileId,  starting  from  the  current
1272              file position.  Check all patterns in the scan context specified
1273              by contexthandle against it, executing the match commands corre‐
1274              sponding to patterns matched.
1275
1276              If  the optional -copyfile argument is specified, the next argu‐
1277              ment is a file ID to which all lines not matched by any  pattern
1278              (excluding  the default pattern) are to be written.  If the copy
1279              file is specified with this flag, instead of using the  scancon‐
1280              text  copyfile  command, the file is disassociated from the scan
1281              context at the end of the scan.
1282
1283              This command does not  work  on  files  containing  binary  data
1284              (bytes of zero).
1285
1286       scanmatch ?-nocase? contexthandle ?regexp? commands
1287
1288              Specify  Tcl commands, to be evaluated when regexp is matched by
1289              a scanfile command.  The match is  added  to  the  scan  context
1290              specified  by contexthandle.  Any number of match statements may
1291              be specified for a give context.  Regexp is a regular expression
1292              (see  the regexp command).  If -nocase is specified as the first
1293              argument, the pattern is matched regardless of alphabetic case.
1294
1295              If regexp is not specified, then a default  match  is  specified
1296              for the scan context.  The default match will be executed when a
1297              line of the file does not match any of the  regular  expressions
1298              in the current scancontext.
1299
1300              The  array  matchInfo  is available to the Tcl code that is exe‐
1301              cuted when an expression matches  (or  defaults).   It  contains
1302              information about the file being scanned and where within it the
1303              expression was matched.
1304
1305              matchInfo is local to the top level of the match command  unless
1306              declared  global at that level by the Tcl global command.  If it
1307              is to be used as a global, it must  be  declared  global  before
1308              scanfile is called (since scanfile sets the matchInfo before the
1309              match code is executed, a subsequent global  will  override  the
1310              local variable).  The following array entries are available:
1311
1312              matchInfo(line)
1313                     Contains  the  text  of  the  line  of  the file that was
1314                     matched.
1315
1316              matchInfo(offset)
1317                     The byte offset into the file of the first  character  of
1318                     the line that was matched.
1319
1320              matchInfo(linenum)
1321                     The  line  number  of  the line that was matched. This is
1322                     relative to the first line scanned, which is usually, but
1323                     not  necessarily,  the first line of the file.  The first
1324                     line is line number one.
1325
1326              matchInfo(context)
1327                     The context handle of the context that this scan is asso‐
1328                     ciated with.
1329
1330              matchInfo(handle)
1331                     The file id (handle) of the file currently being scanned.
1332
1333              matchInfo(copyHandle)
1334                     The  file id (handle) of the file specified by the -copy‐
1335                     file option.  The element does not exist if -copyfile was
1336                     not specified.
1337
1338              matchInfo(submatch0)
1339                     Will  contain the characters matching the first parenthe‐
1340                     sized subexpression.  The second  will  be  contained  in
1341                     submatch1, etc.
1342
1343              matchInfo(subindex0)
1344                     Will  contain  the  a  list  of  the  starting and ending
1345                     indices of the string matching  the  first  parenthesized
1346                     subexpression.    The   second   will   be  contained  in
1347                     subindex1, etc.
1348
1349              All scanmatch patterns that match a line will  be  processed  in
1350              the  order  in which their specifications were added to the scan
1351              context.  The remainder of the scanmatch  pattern-command  pairs
1352              may  be skipped for a file line if a continue is executed by the
1353              Tcl code of a preceding, matched pattern.
1354
1355              If a return is executed in the body of the  match  command,  the
1356              scanfile  command  currently in progress returns, with the value
1357              passed to return as its return value.
1358

MATH COMMANDS

1360       Several extended math commands commands make many additional math func‐
1361       tions available in TclX.  In addition, a set of procedures provide com‐
1362       mand access to the math functions supported by the expr command.
1363
1364
1365       The following procedures provide command interfaces to  the  expr  math
1366       functions.  They  take the same arguments as the expr functions and may
1367       take expressions as arguments.
1368
1369              abs         acos        asin       atan2
1370              atan        ceil        cos        cosh
1371              double      exp         floor      fmod
1372              hypot       int         log10      log
1373              pow         round       sin        sinh
1374              sqrt        tan         tanh
1375
1376       max num1 ?..numN?
1377
1378       expr max(num1, num2)
1379              Returns the argument that has the highest  numeric  value.  Each
1380              argument may be any integer or floating point value.
1381
1382              This  functionality  is also available as a math function max in
1383              the Tcl expr command.
1384
1385       min num1 ?..numN?
1386
1387       expr min(num1, num2)
1388              Returns the argument that has the lowest  numeric  value.   Each
1389              argument may be any integer or floating point value.
1390
1391              This  functionality  is also available as a math function min in
1392              the Tcl expr command.
1393
1394       random limit | seed ?seedval?
1395              Generate a pseudorandom integer number greater than or equal  to
1396              zero  and  less than limit.  If seed is specified, then the com‐
1397              mand resets the random number  generator  to  a  starting  point
1398              derived  from  the seedval. This allows one to reproduce pseudo‐
1399              random number sequences for testing  purposes.   If  seedval  is
1400              omitted, then the seed is set to a value based on current system
1401              state and the current time, providing a  reasonably  interesting
1402              and ever-changing seed.
1403

LIST MANIPULATION COMMANDS

1405       Extended  Tcl provides additional list manipulation commands and proce‐
1406       dures.
1407
1408       intersect lista listb
1409              Procedure to return the logical intersection of two lists.   The
1410              returned list will be sorted.
1411
1412       intersect3 lista listb
1413              Procedure  to  intersects two lists, returning a list containing
1414              three lists:  The first list returned  is  everything  in  lista
1415              that wasn't in listb.  The second list contains the intersection
1416              of the two lists, and the third list contains all  the  elements
1417              that  were  in  listb  but weren't in lista.  The returned lists
1418              will be sorted.
1419
1420       lassign list var ?var...?
1421              Assign successive elements of a list to specified variables.  If
1422              there  are  more variable names than fields, the remaining vari‐
1423              ables are set to the empty string.  If there are  more  elements
1424              than variables, a list of the unassigned elements is returned.
1425
1426              For example,
1427
1428                  lassign {dave 100 200 {Dave Foo}} name uid gid longName
1429
1430              Assigns  name  to  ``dave'', uid to ``100'', gid to ``200'', and
1431              longName to ``Dave Foo''.
1432
1433       lcontain list element
1434              Determine if the element is a list element of list.  If the ele‐
1435              ment  is  contained  in the list, 1 is returned, otherwise, 0 is
1436              returned.
1437
1438       lempty list
1439              Determine if the specified  list  is  empty.   If  empty,  1  is
1440              returned, otherwise, 0 is returned.  This command is an alterna‐
1441              tive to comparing a list to an empty string, however  it  checks
1442              for a string of all whitespaces, which is an empty list.
1443
1444       lmatch ?mode? list pattern
1445
1446              Search  the  elements  of list, returning a list of all elements
1447              matching pattern.  If none match, an empty list is returned.
1448
1449              The mode argument indicates how the elements of the list are  to
1450              be matched against pattern and it must have one of the following
1451              values:
1452
1453              -exact The list element must contain exactly the same string  as
1454                     pattern.
1455
1456              -glob  Pattern  is a glob-style pattern which is matched against
1457                     each list element using the  same  rules  as  the  string
1458                     match command.
1459
1460              -regexp
1461                     Pattern  is  treated  as a regular expression and matched
1462                     against each list element using the  same  rules  as  the
1463                     regexp command.
1464
1465              If mode is omitted then it defaults to -glob.
1466
1467              Only the -exact comparison will work on binary data.
1468
1469       lrmdups list
1470              Procedure  to  remove  duplicate  elements  from  a  list.   The
1471              returned list will be sorted.
1472
1473       lvarcat var string ?string...?
1474              This command treats each string argument as a list and  concate‐
1475              nates them to the end of the contents of var, forming a a single
1476              list.  The list is stored back into var and also returned as the
1477              result.  if var does not exist, it is created.
1478
1479       lvarpop var ?indexExpr? ?string?
1480              The  lvarpop  command  pops (deletes) the element indexed by the
1481              expression indexExpr from the list  contained  in  the  variable
1482              var.   If  index  is  omitted, then 0 is assumed.  If string, is
1483              specified, then the deleted element is replaced by  string.  The
1484              replaced  or  deleted  element is returned.  Thus ``lvarpop argv
1485              0'' returns the first element of argv, setting argv  to  contain
1486              the remainder of the string.
1487
1488              If the expression indexExpr starts with the string end, then end
1489              is replaced with the index of the last element in the list.   If
1490              the  expression  starts  with len, then len is replaced with the
1491              length of the list.
1492
1493       lvarpush var string ?indexExpr?
1494              The lvarpush command pushes (inserts) string as  an  element  in
1495              the list contained in the variable var.  The element is inserted
1496              before position indexExpr in the list. If index is omitted, then
1497              0 is assumed.  If var does not exists, it is created.
1498
1499              If the expression indexExpr starts with the string end, then end
1500              is replaced with the index of the last element in the list.   If
1501              the  expression  starts  with len, then len is replaced with the
1502              length of the list.  Note the a value of end  means  insert  the
1503              string before the last element.
1504
1505       union lista listb
1506              Procedure  to  return  the  logical  union  of the two specified
1507              lists.  Any duplicate elements are removed.
1508

KEYED LISTS

1510       Extended Tcl defines a special type of list referred to as keyed lists.
1511       These  lists  provided  a  structured data type built upon standard Tcl
1512       lists.  This provides a functionality similar to structs in the C  pro‐
1513       gramming language.
1514
1515       A  keyed  list is a list in which each element contains a key and value
1516       pair.  These element pairs are stored as lists  themselves,  where  the
1517       key is the first element of the list, and the value is the second.  The
1518       key-value pairs are referred to as fields.  This is  an  example  of  a
1519       keyed list:
1520
1521                  {{NAME {Frank Zappa}} {JOB {musician and composer}}}
1522
1523       If  the  variable  person contained the above list, then keylget person
1524       NAME would return {Frank Zappa}.  Executing the command:
1525
1526                   keylset person ID 106
1527
1528       would make person contain
1529
1530                  {{ID 106} {NAME {Frank Zappa}} {JOB {musician and composer}}
1531
1532       Fields may contain subfields; `.' is  the  separator  character.   Sub‐
1533       fields are actually fields where the value is another keyed list.  Thus
1534       the following list has the top level fields ID and NAME, and  subfields
1535       NAME.FIRST and  NAME.LAST:
1536
1537                  {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
1538
1539       There  is no limit to the recursive depth of subfields, allowing one to
1540       build complex data structures.
1541
1542       Keyed lists are constructed and accessed via a number of commands.  All
1543       keyed list management commands take the name of the variable containing
1544       the keyed list as an argument (i.e. passed by reference),  rather  than
1545       passing the list directly.
1546
1547       keyldel listvar key
1548              Delete  the  field  specified  by key from the keyed list in the
1549              variable listvar.  This removes both the key and the value  from
1550              the keyed list.
1551
1552       keylget listvar ?key? ?retvar | {}?
1553              Return  the value associated with key from the keyed list in the
1554              variable listvar.  If retvar is not specified,  then  the  value
1555              will be returned as the result of the command.  In this case, if
1556              key is not found in the list, an error will result.
1557
1558              If retvar is specified and key is in the list, then the value is
1559              returned in the variable retvar and the command returns 1 if the
1560              key was present within the list.  If key isn't in the list,  the
1561              command will return 0, and retvar will be left unchanged.  If {}
1562              is specified for retvar, the value is not returned, allowing the
1563              Tcl  programmer to determine if a key is present in a keyed list
1564              without setting a variable as a side-effect.
1565
1566              If key is omitted, then a list of all the keys in the keyed list
1567              is returned.
1568
1569       keylkeys listvar ?key?
1570              Return  the a list of the keys in the keyed list in the variable
1571              listvar.  If keys is specified, then it is the  name  of  a  key
1572              field  who's subfield keys are to be retrieve.
1573
1574       keylset listvar key value ?key2 value2 ...?
1575              Set  the  value associated with key, in the keyed list contained
1576              in the variable listvar, to value.  If listvar does not  exists,
1577              it  is created.  If key is not currently in the list, it will be
1578              added.  If it already exists, value replaces the existing value.
1579              Multiple keywords and values may be specified, if desired.
1580

STRING AND CHARACTER MANIPULATION COMMANDS

1582       The  commands  provide additional functionality to classify characters,
1583       convert characters between character and numeric values, index  into  a
1584       string,  determine the length of a string, extract a range of character
1585       from a string, replicate a string a number of times, and  transliterate
1586       a string (similar to the Unix tr program).
1587
1588       ccollate ?-local? string1 string2
1589              This  command compares two strings.  If returns -1 if string1 is
1590              less than string2, 0 if they are  equal  and  1  if  string1  is
1591              greater than string2.
1592
1593              If  -local  is  specified, the strings are compared according to
1594              the collation environment of the current locale.
1595
1596              This command does not work with binary or UTF data.
1597
1598       cconcat ?string1? ?string2? ?...?
1599              Concatenate  the  arguments,  returning  the  resulting  string.
1600              While  string concatenation is normally performed by the parser,
1601              it is occasionally useful to  have  a  command  that  returns  a
1602              string.   The  is generally useful when a command to evaluate is
1603              required.  No separators are inserted between the strings.
1604
1605              This command is UTF-aware.
1606
1607       cequal string string
1608              This command compares two strings for equality.  It returns 1 if
1609              string1  and  string2  are  the identical and 0 if they are not.
1610              This command is a short-cut for string compare  and  avoids  the
1611              problems  with  string expressions being treated unintentionally
1612              as numbers.
1613
1614              This command is UTF-aware and will also work on binary data.
1615
1616       cindex string indexExpr
1617              Returns the character indexed by the expression indexExpr  (zero
1618              based) from string.
1619
1620              If the expression indexExpr starts with the string end, then end
1621              is replaced with the index of the last character in the  string.
1622              If the expression starts with len, then len is replaced with the
1623              length of the string.
1624
1625              This command is UTF-aware.
1626
1627       clength string
1628              Returns the length of string in characters.  This command  is  a
1629              shortcut for:
1630                  string length string
1631
1632              This command is UTF-aware.
1633
1634       crange string firstExpr lastExpr
1635              Returns  a range of characters from string starting at the char‐
1636              acter indexed by the expression firstExpr (zero-based) until the
1637              character indexed by the expression lastExpr.
1638
1639              If  the  expression firstExpr or lastExpr starts with the string
1640              end, then end is replaced with the index of the  last  character
1641              in  the  string.  If the expression starts with len, then len is
1642              replaced with the length of the string.
1643
1644              This command is UTF-aware.
1645
1646       csubstr string firstExpr lengthExpr
1647              Returns a range of characters from string starting at the  char‐
1648              acter  indexed  by  the  expression  firstExpr  (zero-based) for
1649              lengthExpr characters.
1650
1651              If the expression firstExpr or lengthExpr starts with the string
1652              end,  then  end is replaced with the index of the last character
1653              in the string.  If the expression starts with len, then  len  is
1654              replaced with the length of the string.
1655
1656              This command is UTF-aware.
1657
1658       ctoken strvar separators
1659              Parse a token out of a character string.  The string to parse is
1660              contained in the variable named strvar.  The  string  separators
1661              contains all of the valid separator characters for tokens in the
1662              string.  All leading separators are skipped and the first  token
1663              is  returned.   The  variable strvar will be modified to contain
1664              the remainder of the string following the token.
1665
1666              This command does not work with binary data.
1667
1668       ctype ?-failindex var? class string
1669              ctype determines whether all characters in  string  are  of  the
1670              specified  class.   It returns 1 if they are all of class, and 0
1671              if they are not, or if the string is empty.  This  command  also
1672              provides  another method (besides format and scan) of converting
1673              between an ASCII character and its numeric value.  The following
1674              ctype commands are available:
1675
1676              ctype ?-failindex var? alnum string
1677                     Tests that all characters are alphabetic or numeric char‐
1678                     acters as defined by the character set.
1679
1680              ctype ?-failindex var? alpha string
1681                     Tests that all characters are  alphabetic  characters  as
1682                     defined by the character set.
1683
1684              ctype ?-failindex var? ascii string
1685                     Tests  that all characters are an ASCII character (a non-
1686                     negative number less than 0200).
1687
1688              ctype char number
1689                     Converts the numeric value, string, to an  ASCII  charac‐
1690                     ter.   Number  must be in the range 0 through the maximum
1691                     Unicode values.
1692
1693              ctype ?-failindex var? cntrl string
1694                     Tests that all characters are ``control  characters''  as
1695                     defined by the character set.
1696
1697              ctype ?-failindex var? digit string
1698                     Tests  that all characters are valid decimal digits, i.e.
1699                     0 through 9.
1700
1701              ctype ?-failindex var? graph string
1702                     Tests that all characters within are  any  character  for
1703                     which ctype print is true, except for space characters.
1704
1705              ctype ?-failindex var? lower string
1706                     Tests  that  all  characters  are  lowercase  letters  as
1707                     defined by the character set.
1708
1709              ctype ord character
1710                     Convert a character into its decimal numeric value.   The
1711                     first character of the string is converted to its numeric
1712                     Unicode value.
1713
1714              ctype ?-failindex var? space string
1715                     Tests that all characters are either a space, horizontal-
1716                     tab,  carriage  return,  newline,  vertical-tab, or form-
1717                     feed.
1718
1719              ctype ?-failindex var? print string
1720                     Tests that all characters are a space  or  any  character
1721                     for  which  ctype  alnum  or ctype punct is true or other
1722                     ``printing character'' as defined by the character set.
1723
1724              ctype ?-failindex var? punct string
1725                     Tests that all characters are made up of any of the char‐
1726                     acters  other  than  the  ones for which alnum, cntrl, or
1727                     space is true.
1728
1729              ctype ?-failindex var? upper string
1730                     Tests  that  all  characters  are  uppercase  letters  as
1731                     defined by the character set.
1732
1733              ctype ?-failindex var? xdigit string
1734                     Tests  that  all characters are valid hexadecimal digits,
1735                     that is 0 through 9, a through f or A through F.
1736
1737              If -failindex is specified, then the index into  string  of  the
1738              first character that did not match the class is returned in var.
1739
1740       replicate string countExpr
1741              Returns  string, replicated the number of times indicated by the
1742              expression countExpr.
1743
1744              This command is UTF-aware and will work with binary data.
1745
1746       translit inrange outrange string
1747              Translate characters in string, changing characters occurring in
1748              inrange  to the corresponding character in outrange. Inrange and
1749              outrange may be list of characters or a range in the form `A-M'.
1750              For example:
1751                      translit a-z A-Z foobar
1752
1753              This command currently only supports characters in ASCII range; UTF-8 characters
1754              out of this range will generate an error.
1755

XPG/3 MESSAGE CATALOG COMMANDS

1757       These  commands  provide  a  Tcl interface to message catalogs that are
1758       compliant with the X/Open Portability Guide, Version 3 (XPG/3).
1759
1760       Tcl programmers can use message catalogs to  create  applications  that
1761       are   language-independent.   Through  the  use  of  message  catalogs,
1762       prompts, messages, menus and so forth can exist for any number of  lan‐
1763       guages, and they can altered, and new languages added,  without affect‐
1764       ing any Tcl or C source code, greatly easing the maintenance  difficul‐
1765       ties incurred by supporting multiple languages.
1766
1767       A  default  text  message is passed to the command that fetches entries
1768       from message catalogs.  This allows the Tcl programmer to  create  mes‐
1769       sage  catalogs containing messages in various languages, but still have
1770       a set of default messages available regardless of the presence  of  any
1771       message catalogs, and allow the programs to press on without difficulty
1772       when no catalogs are present.
1773
1774       Thus, the normal approach to using message catalogs is to ignore errors
1775       on  catopen, in which case catgets will return the default message that
1776       was specified in the call.
1777
1778       The Tcl message catalog commands normally ignore most errors.  If it is
1779       desirable to detect errors, a special option is provided.  This is nor‐
1780       mally used only during debugging, to insure that message  catalogs  are
1781       being  used.   If  your Unix implementation does not have XPG/3 message
1782       catalog support, stubs will be compiled in that will create  a  version
1783       of  catgets  that  always  returns the default string.  This allows for
1784       easy porting of software to environments that don't  have  support  for
1785       message catalogs.
1786
1787       Message  catalogs are global to the process, an application with multi‐
1788       ple Tcl interpreters within the same process may pass and share message
1789       catalog handles.
1790
1791       catopen ?-fail | -nofail? catname
1792              Open  the  message catalog catname.  This may be a relative path
1793              name, in which case the NLSPATH environment variable is searched
1794              to  find  an  absolute path to the message catalog.  A handle in
1795              the form msgcatN is returned.  Normally, errors are ignored, and
1796              in the case of a failed call to catopen, a handle is returned to
1797              an unopened message catalog.  (This handle may still  be  passed
1798              to  catgets  and  catclose, causing catgets to simply return the
1799              default string, as described above.   If  the  -fail  option  is
1800              specified,  an  error is returned if the open fails.  The option
1801              -nofail specifies the default behavior of not returning an error
1802              when  catopen fails to open a specified message catalog.  If the
1803              handle from a failed catopen is passed to catgets,  the  default
1804              string is returned.
1805
1806       catgets catHandle setnum msgnum defaultstr
1807              Retrieve a message form a message catalog. CatHandle should be a
1808              Tcl message catalog handle that was returned by catopen.  Setnum
1809              is  the message set number, and msgnum is the message number. If
1810              the message catalog was not opened, or the message set  or  mes‐
1811              sage  number  cannot be found, then the default string, default‐
1812              str, is returned.
1813
1814       catclose ?-fail | -nofail? cathandle
1815              Close the message catalog  specified  by  cathandle.   Normally,
1816              errors  are  ignored.  If -fail is specified, any errors closing
1817              the message catalog file are returned.  The option -nofail spec‐
1818              ifies  the  default behavior of not returning an error.  The use
1819              of -fail only makes sense if it was also specified in  the  call
1820              to catopen.
1821
1822       mainloop
1823              This  procedure sets up a top-level event loop.  Events are pro‐
1824              cessed until there are no more active event  sources,  at  which
1825              time the process exits.  It is used to build event oriented pro‐
1826              grams using the TclX shell in a style similar to that used  with
1827              wish.   If  the global variable tcl_interactive exists and has a
1828              true value an interactive command handler is  started  as  well.
1829              If the command handler is terminated by an EOF, the process will
1830              be exited.
1831

HELP FACILITY

1833       The help facility  allows  one  to  look  up  help  pages  which  where
1834       extracted from the standard Tcl manual pages and Tcl scripts during Tcl
1835       installation.  Help files are structured as a multilevel tree  of  sub‐
1836       jects  and  help  pages.  Help files are found by searching directories
1837       named help in the directories listed in the auto_path variable.  All of
1838       the  files  in  the list of help directories form a virtual root of the
1839       help tree.  This method allows multiple applications  to  provide  help
1840       trees without having the files reside in the same directory.
1841
1842       The  help facility can be accessed in two ways, as interactive commands
1843       in the Extended Tcl shell or as an interactive Tk-based program (if you
1844       have built Extended Tcl with Tk).
1845
1846       To run the Tk-based interactive help program:
1847
1848           tclhelp ?addpaths?
1849
1850       Where addpaths are additional paths to search for help directories.  By
1851       default, only the auto_path used  by  tclhelp  is  search.   This  will
1852       result in help on Tcl, Extended Tcl and Tk.
1853
1854       The  following  interactive  Tcl commands and options are provided with
1855       the help package:
1856
1857       help
1858              Help, without arguments, lists of  all  the  help  subjects  and
1859              pages under the current help subject.
1860
1861       help subject
1862              Displays  all  of  help  pages  and lower level subjects (if any
1863              exist) under the subject subject.
1864
1865       help subject/helppage
1866              Display the specified help page.   The  help  output  is  passed
1867              through a simple pager if output exceeds 23 lines, pausing wait‐
1868              ing for a return to be  entered.   If  any  other  character  is
1869              entered, the output is terminated.
1870
1871       helpcd ?subject?
1872              Change  the current subject, which is much like the Unix current
1873              directory.  If subject is not specified, return to the top-level
1874              of  the  help  tree.   Help  subject path names may also include
1875              ``..'' elements.
1876
1877       helppwd
1878              Displays the current help subject.
1879
1880       help help | ?
1881              Displays help on the help facility at any directory level.
1882
1883       apropos pattern
1884              This  command  locates  subjects  by  searching  their  one-line
1885              descriptions  for  a  pattern.   Apropos  is useful when you can
1886              remember part of the name or description of a command, and  want
1887              to  search  through  the  one-line summaries for matching lines.
1888              Full regular expressions may be specified (see the  regexp  com‐
1889              mand).
1890

TCL LOADABLE LIBRARIES AND PACKAGES

1892       Extended  Tcl  supports  standard  Tcl  tclIndex  libraries and package
1893       libraries. A package library file can contain multiple independent  Tcl
1894       packages.   A  package  is a named collection of related Tcl procedures
1895       and initialization code.
1896
1897       The package library file is just a regular  Unix  text  file,  editable
1898       with your favorite text editor, containing packages of Tcl source code.
1899       The package library file name must have the  suffix  .tlib.   An  index
1900       file  with  the  same prefix name and the suffix .tndx resides the same
1901       directory as the .tlib file.  The .tndx will be  automatically  created
1902       whenever  it  is out of date or missing (provided there is write access
1903       to the directory).
1904
1905       The variable auto_path contains a list of directories that are searched
1906       for  libraries.   The  first  time an unknown command trap is take, the
1907       indexes for the libraries are loaded  into  memory.  If  the  auto_path
1908       variable  is  changed  during  execution  of  a program, it will be re-
1909       searched. Only the first package of a given name found during the  exe‐
1910       cution  of  a  program  is loaded.  This can be overridden with loadli‐
1911       bindex command.
1912
1913       The start of a package is delimited by:
1914
1915              #@package: package_name proc1 ?..procN?
1916
1917       These lines must start in column one.  Everything between  the  #@pack‐
1918       age: keyword and the next #@package: keyword or a #@packend keyword, or
1919       the end of the file, becomes part of the named package.  The  specified
1920       procedures,  proc1..procN, are the entry points of the package.  When a
1921       command named in a package specification is executed and detected as an
1922       unknown  command,  all  code  in the specified package will be sourced.
1923       This package should define all of the procedures named on  the  package
1924       line,  define any support procedures required by the package and do any
1925       package-specific initialization.  Packages declarations maybe continued
1926       on  subsequent  lines  using standard Tcl backslash line continuations.
1927       The #@packend keyword is useful to make sure only the minimum  required
1928       section  of code is sourced.  Thus for example a large comment block at
1929       the beginning of the next file won't be loaded.
1930
1931       Care should be taken in defining package_name,  as  the  first  package
1932       found  in  the path by with a given name is loaded.  This can be useful
1933       in developing new version of packages installed on the system.
1934
1935       For example, in a package source file, the presence  of  the  following
1936       line:
1937
1938              #@package: directory_stack pushd popd dirs
1939
1940       says  that the text lines following that line in the package file up to
1941       the next package line or the end of the file is a package named  direc‐
1942       tory_stack  and  that  an attempt to execute either pushd, popd or dirs
1943       when the routine is not already defined will cause the  directory_stack
1944       portion of the package file to be loaded.
1945

PACKAGE LIBRARY MANAGEMENT COMMANDS

1947       Several  commands  are  available  for  building  and  managing package
1948       libraries.  Commands that are extended versions  of  the  standard  Tcl
1949       library commands are listed here.  All of the standard Tcl library man‐
1950       agement commands and variables are also supported.
1951
1952       auto_commands ?-loaders?
1953              Lists the names of all known loadable  procedures  and  commands
1954              procedures.   If -loaders is specified, the command that will be
1955              executed to load the command will also be returned.
1956
1957       buildpackageindex libfilelist
1958              Build index files for  package  libraries.   The  argument  lib‐
1959              filelist  is  a  list  of package libraries.  Each name must end
1960              with the suffix .tlib.   A  corresponding  .tndx  file  will  be
1961              built.   The  user  must have write access to the directory con‐
1962              taining each library.
1963
1964       convert_lib tclIndex packagelib ?ignore?
1965              Convert a Ousterhout style tclIndex  index  file  and  associate
1966              source  files  into a package library packagelib.  If packagelib
1967              does not have a .tlib extension, one will be added.   Any  files
1968              specified  in  tclIndex  that  are  in  the  list ignore will be
1969              skipped.  Files listed in ignore should just be  the  base  file
1970              names, not full paths.
1971
1972       loadlibindex libfile.tlib
1973              Load  the  package  library  index  of  the library file libfile
1974              (which must have the suffix  .tlib).   Package  library  indexes
1975              along  the  auto_path  are  loaded  automatically  on  the first
1976              demand_load;  this  command  is  provided  to  explicitly   load
1977              libraries  that  are not in the path.  If the index file (with a
1978              .tndx suffix) does not exists or is out  of  date,  it  will  be
1979              rebuilt if the user has directory permissions to create it. If a
1980              package with the same name as  a  package  in  libfile.tlib  has
1981              already  been  loaded,  its definition will be overridden by the
1982              new package.  However, if any procedure has actually  been  used
1983              from  the  previously  defined package, the procedures from lib‐
1984              file.tlib will not be loaded.
1985
1986       auto_packages ?-location?
1987              Returns a list of the names of all defined packages.  If  -loca‐
1988              tion is specified, a list of pairs of package name and the .tlib
1989              path name, offset and length of the package within the library.
1990
1991       auto_load_file file
1992              Source a  file,  as  with  the  source  command,  except  search
1993              auto_path for the file.
1994
1995       searchpath path file
1996              Search  all  directories  in  the specified path, which is a Tcl
1997              list, for the specified file.  Returns the full path name of the
1998              file,  or  an  empty  string  if the requested file could not be
1999              found.
2000
2001
2002
2003
2004
2005Tcl                                                                  TclX(TCL)
Impressum