1TclX(TCL) TclX(TCL)
2
6 TclX - Extended Tcl: Extended command set for Tcl
7
9 package require Tclx
10
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 Extended Tcl was created by Karl Lehenbauer and Mark Diekhans and is
19 freely redistributable for any use without license or fee.
20 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 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 The command descriptions are separated into several sections:
31 · General Commands
33 · Debugging and Development Commands
35 · Unix Access Commands
37 · File Commands
39 · Network Programming Support
41 · File Scanning Commands
43 · Math Commands
45 · List Manipulation Commands
47 · Keyed Lists
49 · String and Character Manipulation Commands
51 · XPG/3 Message Catalog Commands
53 · Help Facility
55 · Tcl Loadable Libraries and Packages
57
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 dirs This procedure lists the directories in the directory stack.
64 commandloop ?-async? ?-interactive on | off | tty? ?-prompt1 cmd?
66 ?-prompt2 cmd? ?-endcommand cmd?
67 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 The following options are available:
77 -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 -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 -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 -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 -endcommand cmd
108 If specified, cmd is evaluated when the command loop ter‐
109 minates.
110 In interactive mode, the results of set commands with two
112 arguments are not printed.
113 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 echo ?str ...?
119 Writes zero or more strings to standard output, followed by a
120 newline.
121 infox option
123 Return information about Extended Tcl, or the current applica‐
125 tion. The following infox command options are available:
126 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 patchlevel
134 Return the patchlevel for Extended Tcl.
135 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 have_fchmod
142 Return 1 if the fchmod system call is available. This
143 supports the -fileid option on the chmod command.
144 have_flock
146 Return 1 if the flock command defined, 0 if it is not
147 available.
148 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 The first, limit and increment are integer expressions. They
245 are only evaluated once at the beginning of the loop.
246 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 popd This procedure pops the top directory entry from the directory
254 stack and make it the current directory.
255 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 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 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 try_eval code catch ?finally?
275 The try_eval command evaluates code in the current context.
276 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 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
294 This section contains information on commands and procedures that are
295 useful for developing and debugging Tcl scripts.
296 cmdtrace level | on ?noeval? ?notruncate? ?procs? ?fileid? ?command
299 cmd?
300 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 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 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 notruncate
319 Disables the truncation of commands and evaluated argu‐
320 ments.
321 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 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 command cmd
337 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 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 cmdtrace on [open cmd.log w]
351 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 command
357 A string containing the text of the command, before any
358 argument substitution.
359 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 evalLevel
365 The Tcl_Eval call level.
366 procLevel
368 The procedure call level.
369 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 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 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 cmdtrace off
386 Turn off all tracing.
387 cmdtrace depth
389 Returns the current maximum trace level, or zero if trace is
390 disabled.
391 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 profile ?-commands? ?-eval? on
400 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 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 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 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 A Tcl procedure profrep is supplied for reducing the data and
435 producing a report.
436 On Windows, profile command only reports elapsed real time, CPU
438 time is not available and is reported as zero.
439 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 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 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
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 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 The alarm command is not available on Windows.
479 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 The -argv0 options specifies that argv0 is to be passed to the
486 program as argv [0] rather than prog.
487 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 kill [id process]
496 On Windows, where the fork command is not available, execl
498 starts a new process and returns the process id.
499 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 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 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 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 The fork command is not available on Windows.
522 id options
524 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 id user ?name?
530 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 id convert userid uid
538 id convert user name
540 Convert a user ID number to a user name, or vice versa.
541 id group ?name?
543 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 id groups
551 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 id convert groupid gid
558 id convert group name
560 Convert a group ID number to a group name, or vice versa.
561 id effective user
563 id effective userid
565 Return the effective user name, or effective user ID num‐
566 ber, respectively.
567 id effective group
569 id effective groupid
571 Return the effective group name, or effective group ID
572 number, respectively.
573 id effective groupids
575 Return all of the groupids the user is a member of.
576 id host
578 Return the hostname of the system the program is running
579 on.
580 id process
582 Return the process ID of the current process.
583 id process parent
585 Return the process ID of the parent of the current
586 process.
587 id process group
589 Return the process group ID of the current process.
590 id process group set
592 Set the process group ID of the current process to its
593 process ID.
594 id host
596 Returns the standard host name of the machine the process
597 is executing on.
598 On Windows, only the host and process options are imple‐
600 mented.
601 kill ?-pgroup ?signal? idlist
603 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 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 On Windows, the kill command is capable of terminating a
616 process, but not of sending an arbitrary signal.
617 link ?-sym? srcpath destpath
619 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 The link command is not available on Windows. Use the Tcl 8.4+
626 file link command instead.
627 nice ?priorityincr?
629 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 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 The new priority is returned.
641 The nice command is not available on Windows.
643 readdir ?-hidden? dirPath
645 Returns a list containing the contents of the directory dirPath.
647 The directory entries "." and ".." are not returned.
648 On Windows, -hidden maybe specified to include hidden files in
650 the result. This flag is ignored on Unix systems.
651 signal ?-restart? action siglist ?command?
653 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 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 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 default
678 Perform system default action when signal is received
679 (see signal system call documentation).
680 ignore Ignore the signal.
682 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 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 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 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 block Block the specified signals from being received. (Posix
719 systems only).
720 unblock
722 Allow the specified signal to be received. Pending sig‐
723 nals will not occur. (Posix systems only).
724 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 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 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 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 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 sync ?fileId?
759 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 If fileId is specified, the file must be writable. A flush will
768 be issued against the fileId before the sync.
769 The infox have_fsync command can be used to determine if "sync
771 fileId" will do a sync or a fsync.
772 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 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 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 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 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 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 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
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 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 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 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 This command does not work on files containing binary data
859 (bytes of zero).
860 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 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 The chmod command is not available on Windows.
873 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 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 The chown command is not available on Windows.
888 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 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 The chgrp command is not available on Windows.
899 dup fileId ?targetFileId?
901 Duplicate an open file. A new file id is opened that addresses
902 the same file as fileId.
903 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 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 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 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 RDONLY The file is opened for reading only. (Get only)
927 WRONLY The file is opened for writing only. (Get only)
929 RDWR The file is opened for reading and writing. (Get only)
931 READ If the file is readable. (Get only).
933 WRITE If the file is writable. (Get only).
935 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 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 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 NOBUF The file is not buffered. If set, then there no buffering for
950 the file.
951 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 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 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 The APPEND and CLOEXEC options are not available on Windows.
969 flock options fileId ?start? ?length? ?origin?
971 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 The following options are recognized:
985 -read Place a read lock on the file. Multiple processes may be
987 accessing the file with read-locks.
988 -write Place a write lock on the file. Only one process may be
990 accessing a file if there is a write lock.
991 -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 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 The flock command is not available on Windows 95. It is avail‐
1003 able on Windows NT.
1004 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 The break and continue commands work as with foreach.
1011 For example, the command
1013 for_file line /etc/passwd {echo $line}
1015 would echo all the lines in the password file.
1017 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 The funlock command is not available on Windows 95. It is
1024 available on Windows NT.
1025 fstat fileId ?item? | ?stat arrayvar?
1027 Obtain status information about an open file.
1029 The following keys are used to identify data items:
1031 atime The time of last access.
1033 ctime The time of last file status change
1035 dev The device containing a directory for the file. This
1037 value uniquely identifies the file system that contains
1038 the file.
1039 gid The group ID of the file's group.
1041 ino The inode number. This field uniquely identifies the
1043 file in a given file system.
1044 mode The mode of the file (see the mknod system call).
1046 mtime Time when the data in the file was last modified.
1048 nlink The number of links to the file.
1050 size The file size in bytes.
1052 tty If the file is associated with a terminal, then 1 other‐
1054 wise 0.
1055 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 uid The user ID of the file's owner.
1061 If one of these keys is specified as item, then that data item
1063 is returned.
1064 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 If only fileId is specified, the command returns the data as a
1070 keyed list.
1071 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 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 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 ftruncate [-fileid] file newsize
1090 Truncate a file to have a length of at most newsize bytes.
1091 If the option -fileid is specified, file is an open file identi‐
1093 fier, otherwise it is a file path.
1094 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 The -fileid option is not available on Windows.
1102 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 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 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 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 If lgets is currently supported on non-blocking files.
1134 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 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 read_file ?-nonewline? fileName
1147 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 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 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 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 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 select {file3 file4 file5} {file6 file7} {} 10.5
1189 could return
1191 {file3 file4} {file6} {}
1193 or perhaps
1195 file3 {} {}
1197 On Windows, only sockets can be used with the select command.
1199 Pipes, as returned by the open command, are not supported.
1200 write_file fileName string ?string...?
1202 This procedure writes the specified strings to the named file.
1203
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 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 The following subcommands are recognized:
1216 addresses
1218 Return the list of IP addresses for host.
1219 official_name
1221 Return official name for host.
1222 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
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 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 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 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 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 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 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 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 This command does not work on files containing binary data
1284 (bytes of zero).
1285 scanmatch ?-nocase? contexthandle ?regexp? commands
1287 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 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 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 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 matchInfo(line)
1313 Contains the text of the line of the file that was
1314 matched.
1315 matchInfo(offset)
1317 The byte offset into the file of the first character of
1318 the line that was matched.
1319 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 matchInfo(context)
1327 The context handle of the context that this scan is asso‐
1328 ciated with.
1329 matchInfo(handle)
1331 The file id (handle) of the file currently being scanned.
1332 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 matchInfo(submatch0)
1339 Will contain the characters matching the first parenthe‐
1340 sized subexpression. The second will be contained in
1341 submatch1, etc.
1342 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 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 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
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 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 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 max num1 ?..numN?
1377 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 This functionality is also available as a math function max in
1383 the Tcl expr command.
1384 min num1 ?..numN?
1386 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 This functionality is also available as a math function min in
1392 the Tcl expr command.
1393 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
1405 Extended Tcl provides additional list manipulation commands and proce‐
1406 dures.
1407 intersect lista listb
1409 Procedure to return the logical intersection of two lists. The
1410 returned list will be sorted.
1411 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 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 For example,
1427 lassign {dave 100 200 {Dave Foo}} name uid gid longName
1429 Assigns name to ``dave'', uid to ``100'', gid to ``200'', and
1431 longName to ``Dave Foo''.
1432 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 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 lmatch ?mode? list pattern
1445 Search the elements of list, returning a list of all elements
1447 matching pattern. If none match, an empty list is returned.
1448 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 -exact The list element must contain exactly the same string as
1454 pattern.
1455 -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 -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 If mode is omitted then it defaults to -glob.
1466 Only the -exact comparison will work on binary data.
1468 lrmdups list
1470 Procedure to remove duplicate elements from a list. The
1471 returned list will be sorted.
1472 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 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 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 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 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 union lista listb
1506 Procedure to return the logical union of the two specified
1507 lists. Any duplicate elements are removed.
1508
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 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 {{NAME {Frank Zappa}} {JOB {musician and composer}}}
1522 If the variable person contained the above list, then keylget person
1524 NAME would return {Frank Zappa}. Executing the command:
1525 keylset person ID 106
1527 would make person contain
1529 {{ID 106} {NAME {Frank Zappa}} {JOB {musician and composer}}
1531 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 {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
1538 There is no limit to the recursive depth of subfields, allowing one to
1540 build complex data structures.
1541 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 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 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 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 If key is omitted, then a list of all the keys in the keyed list
1567 is returned.
1568 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 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
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 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 If -local is specified, the strings are compared according to
1594 the collation environment of the current locale.
1595 This command does not work with binary or UTF data.
1597 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 This command is UTF-aware.
1606 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 This command is UTF-aware and will also work on binary data.
1615 cindex string indexExpr
1617 Returns the character indexed by the expression indexExpr (zero
1618 based) from string.
1619 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 This command is UTF-aware.
1626 clength string
1628 Returns the length of string in characters. This command is a
1629 shortcut for:
1630 string length string
1631 This command is UTF-aware.
1633 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 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 This command is UTF-aware.
1645 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 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 This command is UTF-aware.
1657 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 This command does not work with binary data.
1667 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 ctype ?-failindex var? alnum string
1677 Tests that all characters are alphabetic or numeric char‐
1678 acters as defined by the character set.
1679 ctype ?-failindex var? alpha string
1681 Tests that all characters are alphabetic characters as
1682 defined by the character set.
1683 ctype ?-failindex var? ascii string
1685 Tests that all characters are an ASCII character (a non-
1686 negative number less than 0200).
1687 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 ctype ?-failindex var? cntrl string
1694 Tests that all characters are ``control characters'' as
1695 defined by the character set.
1696 ctype ?-failindex var? digit string
1698 Tests that all characters are valid decimal digits, i.e.
1699 0 through 9.
1700 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 ctype ?-failindex var? lower string
1706 Tests that all characters are lowercase letters as
1707 defined by the character set.
1708 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 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 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 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 ctype ?-failindex var? upper string
1730 Tests that all characters are uppercase letters as
1731 defined by the character set.
1732 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 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 replicate string countExpr
1741 Returns string, replicated the number of times indicated by the
1742 expression countExpr.
1743 This command is UTF-aware and will work with binary data.
1745 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 This command currently only supports characters in ASCII range; UTF-8 characters
1754 out of this range will generate an error.
1755
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 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 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 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 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 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 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 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 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 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
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 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 To run the Tk-based interactive help program:
1847 tclhelp ?addpaths?
1849 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 The following interactive Tcl commands and options are provided with
1855 the help package:
1856 help
1858 Help, without arguments, lists of all the help subjects and
1859 pages under the current help subject.
1860 help subject
1862 Displays all of help pages and lower level subjects (if any
1863 exist) under the subject subject.
1864 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 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 helppwd
1878 Displays the current help subject.
1879 help help | ?
1881 Displays help on the help facility at any directory level.
1882 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
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 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 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 The start of a package is delimited by:
1914 #@package: package_name proc1 ?..procN?
1916 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 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 For example, in a package source file, the presence of the following
1936 line:
1937 #@package: directory_stack pushd popd dirs
1939 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
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 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 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 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 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 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 auto_load_file file
1992 Source a file, as with the source command, except search
1993 auto_path for the file.
1994 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.
2000Tcl TclX(TCL)