Manual Pages for UNIX Darwin command on man TclX

TclX(TCL) TclX(TCL)

NAME

TclX - Extended Tcl: Extended command set for Tcl

SYNOPSIS

ppaacckkaaggee rreeqquuiirree TTccllxx IINNTTRROODDUUCCTTIIOONN This man page contains the documentation for all of the extensions that

are added to Tcl by Extended Tcl (TclX). TclX extends Tcl's capabili-

ties by adding new commands to it, without changing the syntax of stan-

dard Tcl. Extended Tcl is a superset of standard Tcl and is built alongside the standard Tcl sources. Extended Tcl was created by Karl Lehenbauer and Mark Diekhans and is freely redistributable for any use without license or fee.

Available since 1989, Extended Tcl, also known as TclX, not only adds

capabilities to Tcl, but has also been the source of many of the capa-

bilities of the baseline Tcl release, including arrays, files, sockets, file events, and date and time handling, among others.

Extended Tcl introduces a set of new commands and a user-extensible

library of useful Tcl procedures, any of which can be automatically loaded on the first attempt to execute it. The command descriptions are separated into several sections: +o General Commands +o Debugging and Development Commands +o Unix Access Commands +o File Commands +o Network Programming Support +o File Scanning Commands +o Math Commands +o List Manipulation Commands +o Keyed Lists +o String and Character Manipulation Commands +o XPG/3 Message Catalog Commands +o Help Facility +o Tcl Loadable Libraries and Packages GGEENNEERRAALL CCOOMMMMAANNDDSS A set of general, useful Tcl commands, includes a command to begin an interactive session with Tcl, a facility for tracing execution, and a looping command. ddiirrss This procedure lists the directories in the directory stack.

ccoommmmaannddlloooopp ?-aassyynncc? ?-iinntteerraaccttiivvee oonn || ooffff || ttttyy? ?-pprroommpptt11 cmd?

?-pprroommpptt22 cmd? ?-eennddccoommmmaanndd cmd?

Create an interactive command loop reading commands from stdin and writing results to stdout. Command loops are maybe either be blocking or event oriented. This command is useful for Tcl scripts that do not normally converse interactively with a user through a Tcl command interpreter, but which sometimes want to enter this mode, perhaps for debugging or user configuration. The command loop terminates on EOF. The following options are available:

-aassyynncc A command handler will be associated with stdin. When

input is available on stdin, it will be read and accumu-

lated until a full command is available. That command will then be evaluated. An event loop must be entered for input to be read and processed.

-iinntteerraaccttiivvee oonn || ooffff || ttttyy

Enable or disable interactive command mode. In interac-

tive mode, commands are prompted for and the results of comments are printed. The value maybe any boolean value or ttttyy. If ttttyy is used, interactive mode is enabled if stdin is associated with a terminal or terminal emulator. The default is ttttyy.

-pprroommpptt11 cmd

If specified, cmd is used is evaluate and its result used for the main command prompt. If not specified, the command in ttccllpprroommpptt11 is evaluated to output the prompt. Note the difference in behavior, cmd results is used, while ttccllpprroommpptt11 outputs. This is to allow for future

expansion to command loops that write to other than std-

out.

-pprroommpptt22 cmd

If specified, cmd is used is evaluate and its result used for the secondary (continuation) command prompt. If not specified, the command in ttccllpprroommpptt22 is evaluated to output the prompt.

-eennddccoommmmaanndd cmd

If specified, cmd is evaluated when the command loop ter-

minates. In interactive mode, the results of set commands with two arguments are not printed. If SSIIGGIINNTT is configured to generate a Tcl error, it can be used to delete the current command being type without aborting the program in progress. eecchhoo ?str ...? Writes zero or more strings to standard output, followed by a newline. iinnffooxx option

Return information about Extended Tcl, or the current applica-

tion. The following iinnffooxx command options are available: vveerrssiioonn Return the version number of Extended Tcl. The version number for Extended Tcl is generated by combining the base version of the standard Tcl code with another number indicating the version of Extended Tcl being used. ppaattcchhlleevveell Return the patchlevel for Extended Tcl. hhaavveeffcchhoowwnn Return 11 if the ffcchhoowwnn system call is available. This

supports the -ffiilleeiidd option on the cchhoowwnn and cchhggrrpp com-

mands. hhaavveeffcchhmmoodd Return 11 if the ffcchhmmoodd system call is available. This

supports the -ffiilleeiidd option on the cchhmmoodd command.

hhaavveefflloocckk Return 11 if the fflloocckk command defined, 00 if it is not available. hhaavveeffssyynncc Return 11 if the ffssyynncc system call is available and the ssyynncc command will sync individual files. 00 if it is not available and the ssyynncc command will always sync all file buffers. hhaavveeffttrruunnccaattee

Return 11 if the ffttrruunnccaattee or cchhssiizzee system call is avail-

able. If it is, the ffttrruunnccaattee command -ffiilleeiidd option

maybe used. hhaavveemmssggccaattss Return 11 if XPG message catalogs are available, 00 if they are not. The ccaattggeettss is designed to continue to function without message catalogs, always returning the default string. hhaavveeppoossiixxssiiggnnaallss Return 11 if Posix signals are available (bblloocckk and uunnbblloocckk options available for the signal command). 00 is returned if Posix signals are not available. hhaavveessiiggnnaallrreessttaarrtt

Return 11 if restartable signals are available (-rreessttaarrtt

option available for the signal command). 00 is returned if restartable signals are not available. hhaavveettrruunnccaattee Return 11 if the ttrruunnccaattee system call is available. If it is, the ffttrruunnccaattee command may truncate by file path. hhaavveewwaaiittppiidd Return 11 if the wwaaiittppiidd system call is available and the

wwaaiitt command has full functionality. 00 if the wwaaiitt com-

mand has limited functionality. aappppnnaammee Return the symbolic application name of the current application linked with the Extended Tcl library. The C variable ttccllAAppppNNaammee must be set by the application to return an application specific value for this variable. aapppplloonnggnnaammee

Return a natural language name for the current applica-

tion. The C variable ttccllLLoonnggAAppppNNaammee must be set by the application to return an application specific value for this variable. aappppvveerrssiioonn Return the version number for the current application.

The C variable ttccllAAppppVVeerrssiioonn must be set by the applica-

tion to return an application-specific value for this

variable. aappppppaattcchhlleevveell Return the patchlevel for the current application. The C variable ttccllAAppppPPaattcchhlleevveell must be set by the application

to return an application-specific value for this vari-

able. ffoorraarrrraayykkeeyyss var arrayname code

This procedure performs a foreach-style loop for each key in the

named array. The bbrreeaakk and ccoonnttiinnuuee statements work as with ffoorreeaacchh. ffoorrrreeccuurrssiivveegglloobb var dirlist globlist code

This procedure performs a foreach-style loop over recursively

matched files. All directories in dirlist are recursively

searched (breadth-first), comparing each file found against the

file glob patterns in gglloobblliisstt. For each matched file, the variable var is set to the file path and code is evaluated. Symbolic links are not followed. lloooopp var first limit ?increment? body LLoooopp is a looping command, similar in behavior to the Tcl ffoorr statement, except that the lloooopp statement achieves substantially higher performance and is easier to code when the beginning and ending values of a loop are known, and the loop variable is to be incremented by a known, fixed amount every time through the loop.

The var argument is the name of a Tcl variable that will con-

tain the loop index. The loop index is set to the value speci-

fied by first. The Tcl interpreter is invoked upon body zero or more times, where var is incremented by increment every time through the loop, or by one if increment is not specified. Increment can be negative in which case the loop will count downwards. When var reaches limit, the loop terminates without a subsequent

execution of body. For instance, if the original lloooopp parame-

ters would cause lloooopp to terminate, say first was one, limit was

zero and increment was not specified or was non-negative, body

is not executed at all and lloooopp returns. The first, limit and increment are integer expressions. They are only evaluated once at the beginning of the loop. If a ccoonnttiinnuuee command is invoked within body then any remaining commands in the current execution of body are skipped, as in the ffoorr command. If a bbrreeaakk command is invoked within body then the lloooopp command will return immediately. LLoooopp returns an empty string. ppooppdd This procedure pops the top directory entry from the directory stack and make it the current directory. ppuusshhdd ?dir? This procedure pushes the current directory onto the directory stack and ccdd to the specified directory. If the directory is not specified, then the current directory is pushed, but remains unchanged. rreeccuurrssiivveegglloobb dirlist globlist This procedure returns a list of recursively matches files. All

directories in dirlist are recursively searched (breadth-first),

comparing each file found against the file glob patterns in gglloobblliisstt. Symbolic links are not followed. sshhoowwpprroocc ?procname ...? This procedure lists the definition of the named procedures. Loading them if it is not already loaded. If no procedure names are supplied, the definitions of all currently loaded procedures are returned. ttrryyeevvaall code catch ?finally? The ttrryyeevvaall command evaluates code in the current context. If an error occurs during the evaluation and catch is not empty, then catch is evaluated to handler the error. The result of the command, containing the error message, will be stored in a global variable eerrrroorrRReessuulltt. The global variables eerrrroorrRReessuulltt, eerrrroorrIInnffoo and eerrrroorrCCooddee will be imported into the current scope, there is no need to execute a gglloobbaall command. The result of the catch command becomes the result of

the ttrryyeevvaall command. If the error that caused the catch to be evalu-

ate is to be continued, the following command should be used:

eerrrroorr $$eerrrroorrRReessuulltt $$eerrrroorrCCooddee $$eerrrroorrIInnffoo

If the finally argument is supplied and not empty, it is evaluated after the evaluation of the code and the catch commands. If an error occurs during the evaluation of the finally command, it becomes the result of the ttrryyeevvaall command. Otherwise, the result of either code or catch is preserved, as described above. DDEEBBUUGGGGIINNGG AANNDD DDEEVVEELLOOPPMMEENNTT CCOOMMMMAANNDDSS This section contains information on commands and procedures that are useful for developing and debugging Tcl scripts. ccmmddttrraaccee level | oonn ?nnooeevvaall? ?nnoottrruunnccaattee? ?procs? ?fileid? ?ccoommmmaanndd cmd? Print a trace statement for all commands executed at depth of level or below (1 is the top level). If oonn is specified, all commands at any level are traced. The following options are available: nnooeevvaall Causes arguments to be printed unevaluated. If nnooeevvaall is specified, the arguments are printed before evaluation. Otherwise, they are printed afterwards. If the command line is longer than 60 characters, it is truncated to 60 and a "..." is postpended to indicate that there was more output than was displayed. If an evaluated argument contains a space, the entire argument will be enclosed inside of braces (`{}') to allow the reader to visually separate the arguments from each other. nnoottrruunnccaattee

Disables the truncation of commands and evaluated argu-

ments. pprrooccss Enables the tracing of procedure calls only. Commands that aren't procedure calls (i.e. calls to commands that

are written in C, C++ or some object-compatible language)

are not traced if the pprrooccss option is specified. This option is particularly useful for greatly reducing the output of ccmmddttrraaccee while debugging. ffiilleeiidd This is a file id as returned by the ooppeenn command. If specified, then the trace output will be written to the file rather than stdout. A stdio buffer flush is done

after every line is written so that the trace may be mon-

itored externally or provide useful information for debugging problems that cause core dumps. ccoommmmaanndd cmd Call the specified command cmd on when each command is

executed instead of tracing to a file. See the descrip-

tion of the functionally below. This option may not be specified with a ffiilleeiidd. The most common use of this command is to enable tracing to a file during the development. If a failure occurs, a trace is then available when needed. Command tracing will slow down the execution of code, so it should be removed when code is debugged. The following command will enable tracing to a file for the remainder of the program: cmdtrace on [open cmd.log w] The ccoommmmaanndd option causes a user specified trace command to be called for each command executed. The command will have the following arguments appended to it before evaluation: command A string containing the text of the command, before any argument substitution. argv A list of the final argument information that will be

passed to the command after command, variable, and back-

slash substitution. evalLevel The TTccllEEvvaall call level. procLevel The procedure call level. The command should be constructed in such a manner that it will work if additional arguments are added in the future. It is suggested that the command be a pprroocc with the final argument being aarrggss. Tracing will be turned off while the command is being executed. The values of the eerrrroorrIInnffoo and eerrrroorrCCooddee variables will be

saved and restored on return from the command. It is the com-

mand's responsibility to preserve all other state. If an error occurs during the execution of ccoommmmaanndd, an error message is dumped to stderr and the tracing is disabled. The underlying mechanism that this functionality is built on does not support returning an error to the interpreter. ccmmddttrraaccee ooffff Turn off all tracing. ccmmddttrraaccee ddeepptthh Returns the current maximum trace level, or zero if trace is disabled. eeddpprrooccss ?proc...? This procedure writes the named procedures, or all currently defined procedures, to a temporary file, then calls an editor on it (as specified by the EEDDIITTOORR environment variable, or vvii if none is specified), then sources the file back in if it was changed.

pprrooffiillee ?-commands? ?-eval? oonn

pprrooffiillee ooffff arrayVar This command is used to collect a performance profile of a Tcl script. It collects data at the Tcl procedure level. The number of calls to a procedure, and the amount of real and CPU time is collected. Time is also collected for the global context. The

procedure data is collected by bucketing it based on the proce-

dure call stack, this allows determination of how much time is

spent in a particular procedure in each of it's calling con-

texts.

The oonn option enables profile data collection. If the -ccoommmmaannddss

option is specified, data on all commands within a procedure is

collected as well a procedures. Multiple occurrences of a com-

mand within a procedure are not distinguished, but this data may still be useful for analysis. The ooffff option turns off profiling and moves the data collected

to the array arrayVar. The array is address by a list contain-

ing the procedure call stack. Element zero is the top of the stack, the procedure that the data is for. The data in each entry is a list consisting of the procedure call count and the real time and CPU time in milliseconds spent in the procedure (but not any procedures it calls). The list is in the form {count real cpu}. Normally, the variable scope stack is used in reporting where time is spent. Thus upleveled code is reported in the context that it was executed in, not the context that the uplevel was

called in. If the -eevvaall option is specified, the procedure

evaluation (call) stack is used instead of the procedure scope

stack. Upleveled code is reported in the context of the proce-

dure that did the uplevel. A Tcl procedure pprrooffrreepp is supplied for reducing the data and producing a report. On WWiinnddoowwss, profile command only reports elapsed real time, CPU time is not available and is reported as zero. pprrooffrreepp profDataVar sortKey ?outFile? ?userTitle? This procedure generates a report from data collect from the

profile command. PPrrooffDDaattaaVVaarr is the name of the array contain-

ing the data returned by the pprrooffiillee command. SSoorrttKKeeyy indicates which data value to sort by. It should be one of "ccaallllss", "ccppuu" or "rreeaall". OOuuttFFiillee is the name of file to write the report to. If omitted, stdout is assumed. UUsseerrTTiittllee is an optional title line to add to output. Listed with indentation below each procedure or command is the

procedure call stack. The first indented line being the proce-

dure that invoked the reported procedure or command. The next line is the procedure that invoked the procedure above it, and so on. If no indented procedures are shown, the procedure or command was called from the global context. Time actually spent in the global context is listed on a line labeled <>. Upleveled code is reported in the context that it was executed in, not the context that the uplevel was called in. ssaavveepprrooccss fileName ?proc...? This procedure saves the definition of the named procedure, or all currently defined procedures if none is specified, to the named file. UUNNIIXX AACCCCEESSSS CCOOMMMMAANNDDSS These commands provide access to many basic Unix facilities, including process handling, date and time processing, signal handling and the executing commands via the shell. aallaarrmm seconds Instructs the system to send a SIGALRM signal in the specified

number of seconds. This is a floating point number, so frac-

tions of a section may be specified. If seconds is 0.0, any previous alarm request is canceled. Only one alarm at a time may be active; the command returns the number of seconds left in the previous alarm. On systems without the sseettiittiimmeerr system call, seconds is rounded up to an integer number of seconds. The aallaarrmm command is not available on WWiinnddoowwss.

eexxeeccll ?-aarrggvv00 argv0? prog ?arglist?

Do an execl, replacing the current program (either Extended Tcl or an application with Extended Tcl embedded into it) with prog and passing the arguments in the list arglist.

The -aarrggvv00 options specifies that argv0 is to be passed to the

program as argv [0] rather than prog. Note: If you are using eexxeeccll in a Tk application and it fails, you may not do anything that accesses the X server or you will

receive a BBaaddWWiinnddooww error from the X server. This includes exe-

cuting the Tk version of the eexxiitt command. We suggest using the

following command to abort Tk applications after an eexxeeccll fail-

ure: kill [id process] On WWiinnddoowwss, where the ffoorrkk command is not available, eexxeeccll starts a new process and returns the process id. cchhrroooott dirname Change root directory to dirname, by invoking the POSIX cchhrroooott((22)) system call. This command only succeeds if running as root. ffoorrkk Fork the current Tcl process. Fork returns zero to the child process and the process number of the child to the parent process. If the fork fails, a Tcl error is generated. If an eexxeeccll is not going to be performed before the child process does output, or if a cclloossee and dduupp sequence is going to be performed on ssttddoouutt or ssttddeerrrr, then a fflluusshh should be issued against ssttddoouutt, ssttddeerrrr and any other open output file before doing the ffoorrkk. Otherwise characters from the parent process pending in the buffers will be output by both the parent and child processes. Note: If you are ffoorrkking in a Tk based application you must eexxeeccll before doing any window operations in the child or you will receive a BBaaddWWiinnddooww error from the X server. The ffoorrkk command is not available on WWiinnddoowwss. iidd ooppttiioonnss This command provides a means of getting, setting and converting user, group and process ids. The iidd command has the following options: iidd uusseerr ?name? iidd uusseerriidd ?uid? Set the real and effective user ID to name or uid, if the name (or uid) is valid and permissions allow it. If the name (or uid) is not specified, the current name (or uid) is returned. iidd ccoonnvveerrtt uusseerriidd uid iidd ccoonnvveerrtt uusseerr name Convert a user ID number to a user name, or vice versa. iidd ggrroouupp ?name? iidd ggrroouuppiidd ?gid? Set the real and effective group ID to name or gid, if the name (or gid) is valid and permissions allow it. If the group name (or gid) is not specified, the current group name (or gid) is returned. iidd ggrroouuppss iidd ggrroouuppiiddss Return the current group access list of the process. The option ggrroouuppss returns group names and ggrroouuppiiddss returns id numbers. iidd ccoonnvveerrtt ggrroouuppiidd gid iidd ccoonnvveerrtt ggrroouupp name Convert a group ID number to a group name, or vice versa. iidd eeffffeeccttiivvee uusseerr iidd eeffffeeccttiivvee uusseerriidd

Return the effective user name, or effective user ID num-

ber, respectively. iidd eeffffeeccttiivvee ggrroouupp iidd eeffffeeccttiivvee ggrroouuppiidd Return the effective group name, or effective group ID number, respectively. iidd eeffffeeccttiivvee ggrroouuppiiddss Return all of the groupids the user is a member of. iidd hhoosstt Return the hostname of the system the program is running on. iidd pprroocceessss Return the process ID of the current process. iidd pprroocceessss ppaarreenntt Return the process ID of the parent of the current process. iidd pprroocceessss ggrroouupp Return the process group ID of the current process. iidd pprroocceessss ggrroouupp sseett Set the process group ID of the current process to its process ID. iidd hhoosstt Returns the standard host name of the machine the process is executing on.

On WWiinnddoowwss, only the hhoosstt and pprroocceessss options are imple-

mented.

kkiillll ?-ppggrroouupp ?signal? idlist

Send a signal to the each process in the list idlist, if permit-

ted. Signal, if present, is the signal number or the symbolic name of the signal, see the signal system call manual page. The leading ``SIG'' is optional when the signal is specified by its symbolic name. The default for signo is 15, SIGTERM.

If -ppggrroouupp is specified, the numbers in idlist are take as

process group ids and the signal is sent to all of the process in that process group. A process group id of 00 specifies the current process group. On WWiinnddoowwss, the kkiillll command is capable of terminating a process, but not of sending an arbitrary signal.

lliinnkk ?-ssyymm? srcpath destpath

Create a directory entry, destpath, linking it to the existing

file, srcpath. If -ssyymm is specified, a symbolic link, rather

than a hard link, is created. (The -ssyymm option is only avail-

able on systems that support symbolic links.) The lliinnkk command is not available on WWiinnddoowwss. Use the Tcl 8.4+ ffiillee lliinnkk command instead. nniiccee ?priorityincr?

Change or return the process priority. If priorityincr is omit-

ted, the current priority is returned. If priorityincr is posi-

tive, it is added to the current priority level, up to a system defined maximum (normally 1199), Negative priorityincr values cumulatively increase the program's

priority down to a system defined minimum (normally -1199);

increasing priority with negative niceness values will only work for the superuser. The new priority is returned. The nniiccee command is not available on WWiinnddoowwss.

rreeaaddddiirr ?-hidden? dirPath

Returns a list containing the contents of the directory dirPath. The directory entries "." and ".." are not returned.

On WWiinnddoowwss, -hhiiddddeenn maybe specified to include hidden files in

the result. This flag is ignored on Unix systems.

ssiiggnnaall ?-restart? action siglist ?command?

Warning: If signals are being used as an event source (a ttrraapp action), rather than generating an error to terminate a task;

one must use the -rreessttaarrtt option. This causes a blocked system

call, such as rreeaadd or wwaaiittppiidd to be restarted rather than gener-

ate an error. Failure to do this may results in unexpected errors when a signal arrives while in one of these system calls.

When available, the -rreessttaarrtt option can prevent this problem.

If -rreessttaarrtt is specified, restart blocking system calls rather

than generating an error. The signal will be handled once the

Tcl command that issued the system call completes. The -rreessttaarrtt

options is not available on all operating systems and its use will generate an error when it is not supported. Use iinnffooxx hhaavveessiiggnnaallrreessttaarrtt to check for availability. Specify the action to take when a Unix signal is received by Extended Tcl, or a program that embeds it. Siglist is a list of either the symbolic or numeric Unix signal (the SIG prefix is

optional). Action is one of the following actions to be per-

formed on receipt of the signal. To specify all modifiable sig-

nals, use `*' (this will not include SIGKILL and SIGSTOP, as they can not be modified). ddeeffaauulltt Perform system default action when signal is received (see ssiiggnnaall system call documentation). iiggnnoorree Ignore the signal. eerrrroorr Generate a catchable Tcl error. It will be as if the command that was running returned an error. The error code will be in the form: PPOOSSIIXX SSIIGG signame For the death of child signal, signame will always be SIGCHLD, rather than SIGCLD, to allow writing portable code.

ttrraapp When the signal occurs, execute command and continue exe-

cution if an error is not returned by command. The com-

mand will be executed in the global context. The command will be edited before execution, replacing occurrences of

"%S" with the signal name. Occurrences of "%%" result in

a single "%". This editing occurs just before the trap

command is evaluated. If an error is returned, then fol-

low the standard Tcl error mechanism. Often command will just do an eexxiitt. ggeett Retrieve the current settings of the specified signals. A keyed list will be returned were the keys are one of

the specified signals and the values are a list consist-

ing of the action associated with the signal, a 00 if the signal may be delivered (not block) and a 11 if it is blocked and a flag indicating if restarting of system calls is specified. The actions maybe one of `ddeeffaauulltt',`iiggnnoorree', `eerrrroorr' or `ttrraapp'. If the action is trap, the third element is the command associated with

the action. The action `uunnkknnoowwnn' is returned if a non-

Tcl signal handler has been associated with the signal. sseett Set signals from a keyed list in the format returned by the ggeett. For this action, siglist is the keyed list of signal state. Signals with an action of `uunnkknnoowwnn' are not modified. bblloocckk Block the specified signals from being received. (Posix systems only). uunnbblloocckk

Allow the specified signal to be received. Pending sig-

nals will not occur. (Posix systems only). The signal action will remain enabled after the specified signal

has occurred. The exception to this is SSIIGGCCHHLLDD on systems with-

out Posix signals. For these systems, SSIIGGCCHHLLDD is not be auto-

matically reenabled. After a SSIIGGCCHHLLDD signal is received, a call to wwaaiitt must be performed to retrieve the exit status of the child process before issuing another ssiiggnnaall SSIIGGCCHHLLDD ... command. For code that is to be portable between both types of systems, use this approach. Signals are not processed until after the completion of the Tcl command that is executing when the signal is received. If an interactive Tcl shell is running, then the SSIIGGIINNTT will be set to

eerrrroorr, non-interactive Tcl sessions leave SSIIGGIINNTT unchanged from

when the process started (normally ddeeffaauulltt for foreground pro-

cesses and iiggnnoorree for processes in the background). sslleeeepp seconds Sleep the Extended Tcl process for seconds seconds. Seconds, if specified as a decimal number, is truncated to an integer value. ssyysstteemm cmdstr1 ?cmdstr2...? Concatenates cmdstr1, cmdstr2 etc with space separators (see the ccoonnccaatt command) into a single command and then evaluates the command using the standard system shell. On Unix systems, this is //bbiinn//sshh and on Windows its ccoommmmaanndd..ccoomm. The exit code of the command is returned. This command differs from the eexxeecc command in that ssyysstteemm doesn't return the executed command's standard output as the result string, and ssyysstteemm goes through the Unix shell to provide wild card expansion, redirection, etc, as is normal from an sshh command line. ssyynncc ?fileId? If fileId is not specified, or if it is and this system does not support the fsync system call, issues a sync system call to flush all pending disk output. If fileId is specified and the system does support the fsync system call, issues an fsync on the file corresponding to the specified Tcl fileId to force all pending output to that file out to the disk. If fileId is specified, the file must be writable. A fflluusshh will be issued against the fileId before the sync. The infox havefsync command can be used to determine if "ssyynncc fileId" will do a sync or a fsync. ttiimmeess Return a list containing the process and child execution times in the form: utime stime cutime cstime Also see the times(2) system call manual page. The values are in milliseconds. uummaasskk ?octalmask?

Sets file-creation mode mask to the octal value of octalmask.

If octalmask is omitted, the current mask is returned.

wwaaiitt ?-nnoohhaanngg? ?-uunnttrraacceedd? ?-ppggrroouupp? ?pid?

Waits for a process created with the eexxeeccll command to terminate, either due to an untrapped signal or call to exit system call. If the process id pid is specified, they wait on that process, otherwise wait on any child process to terminate.

If -nnoohhaanngg is specified, then don't block waiting on a process

to terminate. If no process is immediately available, return an

empty list. If -uunnttrraacceedd is specified then the status of child

processes that are stopped, and whose status has not yet been

reported since they stopped, are also returned. If -ppggrroouupp is

specified and pid is not specified, then wait on any child process whose process group ID is they same as the calling

process. If pid is specified with -ppggrroouupp, then it is take as a

process group ID, waiting on any process in that process group to terminate. WWaaiitt returns a list containing three elements: The first element is the process id of the process that terminated. If the process exited normally, the second element is `EXIT', and the third contains the numeric exit code. If the process terminated

due to a signal, the second element is `SIG', and the third con-

tains the signal name. If the process is currently stopped (on

systems that support SIGSTP), the second element is `STOP', fol-

lowed by the signal name. Note that it is possible to wait on processes to terminate that were create in the background with the eexxeecc command. However,

if any other eexxeecc command is executed after the process termi-

nates, then the process status will be reaped by the eexxeecc com-

mand and will not be available to the wwaaiitt command.

On systems without the wwaaiittppiidd system call, the -nnoohhaanngg,

-uunnttrraacceedd and -ppggrroouupp options are not available. The iinnffooxx

hhaavveewwaaiittppiidd command maybe use to determine if this functional-

ity is available. FFIILLEE CCOOMMMMAANNDDSS These commands provide extended file access and manipulation. This

includes searching ASCII-sorted data files, copying files, duplicating

file descriptors, control of file access options, retrieving open file status, and creating pipes with the ppiippee system call. Also linking files, setting file, process, and user attributes and truncating files. An interface to the sseelleecctt system call is available on Unix systems that support it. It should be noted that Tcl file I/O is implemented on top of the stdio library. By default, the file is buffered. When communicating to a process through a pipe, a fflluusshh command should be issued to force the data out. Alternatively, the ffccnnttll command may be used to set the

buffering mode of a file to line-buffered or unbuffered.

bbsseeaarrcchh fileId key ?retvar? ?compareproc? Search an opened file fileId containing lines of text sorted into ascending order for a match. Key contains the string to match. If retvar is specified, then the line from the file is returned in retvar, and the command returns 11 if key was found, and 00 if it wasn't. If retvar is not specified or is a null name, then the command returns the line that was found, or an empty string if key wasn't found.

By default, the key is matched against the first white-space

separated field in each line. The field is treated as an ASCII string. If compareproc is specified, then it defines the name of a Tcl procedure to evaluate against each line read from the

sorted file during the execution of the bbsseeaarrcchh command. Com-

pareproc takes two arguments, the key and a line extracted from the file. The compare routine should return a number less than zero if the key is less than the line, zero if the key matches the line, or greater than zero if the key is greater than the line. The file must be sorted in ascending order according to the same criteria compareproc uses to compare the key with the line, or erroneous results will occur. This command does not work on files containing binary data (bytes of zero).

cchhmmoodd [-ffiilleeiidd] mode filelist

Set permissions of each of the files in the list filelist to

mode, where mode is an absolute numeric mode or symbolic permis-

sions as in the UNIX cchhmmoodd((11)) command. To specify a mode as octal, it should be prefixed with a "0" (e.g. 0622).

If the option -ffiilleeiidd is specified, filelist is a list of open

file identifiers rather than a list of file names. This option is not available on all Unix systems. Use the iinnffooxx hhaavveeffcchhmmoodd command to determine if this functionality is available. The cchhmmoodd command is not available on WWiinnddoowwss.

cchhoowwnn [-ffiilleeiidd] owner | {owner group} filelist

Set owner of each file in the list filelist to owner, which can be a user name or numeric user id. If the first parameter is a list, then the owner is set to the first element of the list and the group is set to the second element. Group can be a group name or numeric group id. If group is {}, then the file group will be set to the login group of the specified user.

If the option -ffiilleeiidd is specified, filelist is a list of open

cchhggrrpp [-ffiilleeiidd] group filelist

Set the group id of each file in the list filelist to group, which can be either a group name or a numeric group id.

If the option -ffiilleeiidd is specified, filelist is a list of open

file identifiers rather than a list of file names. This option is not available on all Unix systems. Use the iinnffooxx hhaavveeffcchhoowwnn command to determine if this functionality is available. The cchhggrrpp command is not available on WWiinnddoowwss. dduupp fileId ?targetFileId? Duplicate an open file. A new file id is opened that addresses the same file as fileId.

If targetFileId is specified, the the file is dup to this speci-

fied file id. Normally this is ssttddiinn, ssttddoouutt, or ssttddeerrrr. The dup command will handle flushing output and closing this file. The new file will be buffered, if its needs to be unbuffered, use the ffccnnttll command to set it unbuffered. If fileId is a number rather than a Tcl file id, then the dduupp command will bind that file to a Tcl file id. This is useful for accessing files that are passed from the parent process. The argument ?targetFileId? is not valid with this operation.

On WWiinnddoowwss, only ssttddiinn, ssttddoouutt, or ssttddeerrrr or a non-socket file

handle number maybe specified for targetFileId. The dduupp command does not work on sockets on WWiinnddoowwss. ffccnnttll fileId attribute ?value? This command either sets or clears a file option or returns its current value. If value is not specified, then the current value of aattttrriibbuuttee is returned. All values are boolean. Some attributes maybe only be gotten, not modified. The following attributes may be specified: RRDDOONNLLYY The file is opened for reading only. (Get only) WWRROONNLLYY The file is opened for writing only. (Get only) RRDDWWRR The file is opened for reading and writing. (Get only) RREEAADD If the file is readable. (Get only). WWRRIITTEE If the file is writable. (Get only).

AAPPPPEENNDD The file is opened for append-only writes. All writes will be

forced to the end of the file. (Get or set). NNOONNBBLLOOCCKK

The file is to be accessed with non-blocking I/O. See the rreeaadd

system call for a description of how it affects the behavior of file reads. CCLLOOEEXXEECC Close the file on an process exec. If the eexxeeccll command or some other mechanism causes the process to do an exec, the file will be closed if this option is set. NNOOBBUUFF The file is not buffered. If set, then there no buffering for the file. LLIINNEEBBUUFF Output the file will be line buffered. The buffer will be flushed when a newline is written, when the buffer is full, or when input is requested. KKEEEEPPAALLIIVVEE Keep a socket connection alive. If SIGPIPE is enabled, then it is sent if connection is broken and data is written to the socket. If SIGPIPE is ignored, an error is returned on the write. This attribute is valid only on sockets. By default, SIGPIPE is ignored in Tcl. The NNOONNBBLLOOCCKK, NNOOBBUUFF and LLIINNEEBBUUFF are provided for compatibility with older scripts. Theffccoonnffiigguurree command is preferred method of getting and setting these attributes. The AAPPPPEENNDD and CCLLOOEEXXEECC options are not available on WWiinnddoowwss. fflloocckk options fileId ?start? ?length? ?origin? This command places a lock on all or part of the file specified by fileId. The lock is either advisory or mandatory, depending on the mode bits of the file. The lock is placed beginning at relative byte offset start for length bytes. If start or length is omitted or empty, zero is assumed. If length is zero, then the lock always extents to end of file, even if the file grows.

If origin is "ssttaarrtt", then the offset is relative to the begin-

ning of the file. If it is "ccuurrrreenntt", it is relative to the cur-

rent access position in the file. If it is "eenndd", then it is

relative to the end-of-file (a negative is before the EOF, posi-

tive is after). If origin is omitted, ssttaarrtt is assumed. The following options are recognized:

-rreeaadd Place a read lock on the file. Multiple processes may be

accessing the file with read-locks.

-wwrriittee Place a write lock on the file. Only one process may be

accessing a file if there is a write lock.

-nnoowwaaiitt

If specified, then the process will not block if the lock can not be obtained. With this option, the command returns 1 if the lock is obtained and 0 if it is not. See your system's ffccnnttll system call documentation for full details of the behavior of file locking. If locking is being done on ranges of a file, it is best to use unbuffered file access (see the ffccnnttll command).

The fflloocckk command is not available on WWiinnddoowwss 9955. It is avail-

able on WWiinnddoowwss NNTT. ffoorrffiillee var filename code This procedure implements a loop over the contents of a file. For each line in filename, it sets var to the line and executes code. The bbrreeaakk and ccoonnttiinnuuee commands work as with foreach. For example, the command

forfile line /etc/passwd {echo $line}

would echo all the lines in the password file. ffuunnlloocckk fileId ?start? ?length? ?origin? Remove a locked from a file that was previously placed with the

flock command. The arguments are the same as for the flock com-

mand, see that command for more details. The ffuunnlloocckk command is not available on WWiinnddoowwss 9955. It is available on WWiinnddoowwss NNTT. ffssttaatt fileId ?item? | ?ssttaatt arrayvar? Obtain status information about an open file. The following keys are used to identify data items: aattiimmee The time of last access. ccttiimmee The time of last file status change ddeevv The device containing a directory for the file. This value uniquely identifies the file system that contains the file. ggiidd The group ID of the file's group. iinnoo The inode number. This field uniquely identifies the file in a given file system. mmooddee The mode of the file (see the mmkknnoodd system call). mmttiimmee Time when the data in the file was last modified. nnlliinnkk The number of links to the file. ssiizzee The file size in bytes.

ttttyy If the file is associated with a terminal, then 1 other-

wise 0. ttyyppee The type of the file in symbolic form, which is one of the following values: ffiillee, ddiirreeccttoorryy, cchhaarraacctteerrSSppeecciiaall, bblloocckkSSppeecciiaall, ffiiffoo, lliinnkk, or ssoocckkeett. uuiidd The user ID of the file's owner. If one of these keys is specified as item, then that data item is returned. If ssttaatt arrayvar is specified, then the information is returned

in the array arrayvar. Each of the above keys indexes an ele-

ment of the array containing the data. If only fileId is specified, the command returns the data as a keyed list. The following values may be returned only if explicitly asked for, it will not be returned with the array or keyed list forms: rreemmootteehhoosstt If fileId is a TCP/IP socket connection, then a list is returned with the first element being the remote host IP address. If the remote host name can be found, it is returned as the second element of the list. The remote host IP port number is the third element. llooccaallhhoosstt If fileId is a TCP/IP socket connection, then a list is returned with the first element being the local host IP address. If the local host name can be found, it is returned as the second element of the list. The local host IP port number is the third element.

ffttrruunnccaattee [-ffiilleeiidd] file newsize

Truncate a file to have a length of at most newsize bytes.

If the option -ffiilleeiidd is specified, file is an open file identi-

fier, otherwise it is a file path. This command is not available or not fully functional if the

underlying operating system support is not available. The com-

mand iinnffooxx hhaavveettrruunnccaattee will indicate if this command may trun-

cate by file path. The command iinnffooxx hhaavveeffttrruunnccaattee will indi-

cate if this command may truncate by file id.

The -ffiilleeiidd option is not available on WWiinnddoowwss.

llggeettss fileId ?varName?

Reads the next Tcl list from the file given by fileId and dis-

cards the terminating newline character. This command differs from the ggeettss command, in that it reads Tcl lists rather than lines. If the list contains newlines or binary data, then that newline or bytes of zero will be returned as part of the result. Only a newline not quoted as part of the list indicates the end of the list. There is no corresponding command for outputting lists, as ppuuttss will do this correctly. If varName is specified, then the line is placed in the variable by that name and the return value is a count of the number of characters read (not including the newline). If the end of the

file is reached before reading any characters then -1 is

returned and varName is set to an empty string. If varName is specified and an error occurs, what ever data was read will be returned in the variable, however the resulting string may not be a valid list. If varName is not specified then the return value will be the line (minus the newline character) or an empty string if the end of the file is reached before reading any characters. An empty string will also be returned if a line contains no characters except the newline, so eeooff may have to be used to determine what really happened. The llggeettss command maybe used to read and write lists containing binary data, however translation must be set to llff or the data maybe corrupted.

If llggeettss is currently supported on non-blocking files.

ppiippee ?fileIdvarr fileIdvarw? Create a pipe. If fileIdvarr and fileIdvarr are specified, then ppiippee will set the a variable named fileIdvarr to contain the fileId of the side of the pipe that was opened for reading, and fileIdvarw will contain the fileId of the side of the pipe that was opened for writing.

If the fileId variables are not specified, then a list contain-

ing the read and write fileIdw is returned as the result of the command.

rreeaaddffiillee ?-nnoonneewwlliinnee? fileName

rreeaaddffiillee fileName numBytes This procedure reads the file fileName and returns the contents

as a string. If -nnoonneewwlliinnee is specified, then the last charac-

ter of the file is discarded if it is a newline. The second form specifies exactly how many bytes will be read and returned, unless there are fewer than numBytes bytes left in the file; in this case, all the remaining bytes are returned. sseelleecctt readfileIds ?writefileIds? ?exceptfileIds? ?timeout? This command allows an Extended Tcl program to wait on zero or

more files being ready for for reading, writing, have an excep-

tional condition pending, or for a timeout period to expire. readFileIds, writeFileIds, exceptFileIds are each lists of fileIds, as returned from ooppeenn, to query. An empty list ({}) may be specified if a category is not used. The files specified by the readFileIds list are checked to see if data is available for reading. The writeFileIds are checked if the specified files are clear for writing. The exceptFileIds are checked to see if an exceptional condition has occurred (typically, an error). The write and exception checking is most useful on devices, however, the read checking is very useful when communicating with multiple processes through pipes. Select considers data pending in the stdio input buffer for read files as being ready for reading, the files do. not have to be unbuffered. Timeout is a floating point timeout value, in seconds. If an empty list is supplied (or the parameter is omitted), then no timeout is set. If the value is zero, then the sseelleecctt command functions as a poll of the files, returning immediately even if none are ready. If the timeout period expires with none of the files becoming ready, then the command returns an empty list. Otherwise the command returns a list of three elements, each of those elements is a list of the fileIds that are ready in the read, write and

exception classes. If none are ready in a class, then that ele-

ment will be the null list. For example: select {file3 file4 file5} {file6 file7} {} 10.5 could return {file3 file4} {file6} {} or perhaps file3 {} {} On WWiinnddoowwss, only sockets can be used with the sseelleecctt command. Pipes, as returned by the ooppeenn command, are not supported. wwrriitteeffiillee fileName string ?string...? This procedure writes the specified strings to the named file. NNEETTWWOORRKK PPRROOGGRRAAMMMMIINNGG SSUUPPPPOORRTT

TclX provides functionality to complement the Tcl ssoocckkeett command. The

hhoossttiinnffoo command is used to get information about a host by name or IP address. In addition, the ffssttaatt and ffccnnttll commands provide options of querying and controlling connected sockets. To obtain the host name of the system the local system, use the iidd hhoosstt command. hhoossttiinnffoo aaddddrreesssseess host hhoossttiinnffoo ooffffiicciiaallnnaammee host hhoossttiinnffoo aalliiaasseess host Obtain information about a Internet host. The argument host can be either a host name or an IP address. The following subcommands are recognized: aaddddrreesssseess Return the list of IP addresses for host. ooffffiicciiaallnnaammee Return official name for host. aalliiaasseess Return the list of aliases for host. (Note that these

are IP number aliases, not DNS CNAME aliases. See ifcon-

fig(2).) FFIILLEE SSCCAANNNNIINNGG CCOOMMMMAANNDDSS These commands provide a facility to scan files, matching lines of the file against regular expressions and executing Tcl code on a match. With this facility you can use Tcl to do the sort of file processing that is traditionally done with awk. And since Tcl's approach is more declarative, some of the scripts that can be rather difficult to write in awk are simple to code in Tcl. File scanning in Tcl centers around the concept of a scan context. A scan context contains one or more match statements, which associate regular expressions to scan for with Tcl code to be executed when the expressions are matched. ssccaannccoonntteexxtt ?option? This command manages file scan contexts. A scan context is a collection of regular expressions and commands to execute when that regular expression matches a line of the file. A context may also have a single default match, to be applied against

lines that do not match any of the regular expressions. Multi-

ple scan contexts may be defined and they may be reused on mul-

tiple files. A scan context is identified by a context handle. The ssccaannccoonntteexxtt command takes the following forms: ssccaannccoonntteexxtt ccrreeaattee Create a new scan context. The ssccaannmmaattcchh command is used to define patterns in the context. A contexthandle is returned, which the Tcl programmer uses to refer to the newly created scan context in calls to the Tcl file scanning commands. ssccaannccoonntteexxtt ddeelleettee contexthandle Delete the scan context identified by contexthandle, and free all of the match statements and compiled regular expressions associated with the specified context. ssccaannccoonntteexxtt ccooppyyffiillee contexthandle ?filehandle? Set or return the file handle that unmatched lines are copied to. (See ssccaannffiillee). If filehandle is omitted, the copy file

handle is returned. If no copy file is associated with the con-

text, {} is returned. If a file handle is specified, it becomes the copy file for this context. If filehandle is {}, then it removes any copy file specification for the context.

ssccaannffiillee ?-copyfile copyFileId? contexthandle fileId

Scan the file specified by fileId, starting from the current file position. Check all patterns in the scan context specified

by contexthandle against it, executing the match commands corre-

sponding to patterns matched.

If the optional -copyfile argument is specified, the next argu-

ment is a file ID to which all lines not matched by any pattern (excluding the default pattern) are to be written. If the copy

file is specified with this flag, instead of using the ssccaannccoonn-

tteexxtt ccooppyyffiillee command, the file is disassociated from the scan context at the end of the scan. This command does not work on files containing binary data (bytes of zero).

ssccaannmmaattcchh ?-nocase? contexthandle ?regexp? commands

Specify Tcl commands, to be evaluated when regexp is matched by a ssccaannffiillee command. The match is added to the scan context specified by contexthandle. Any number of match statements may be specified for a give context. Regexp is a regular expression

(see the rreeggeexxpp command). If -nnooccaassee is specified as the first

argument, the pattern is matched regardless of alphabetic case. If regexp is not specified, then a default match is specified for the scan context. The default match will be executed when a line of the file does not match any of the regular expressions in the current scancontext.

The array mmaattcchhIInnffoo is available to the Tcl code that is exe-

cuted when an expression matches (or defaults). It contains information about the file being scanned and where within it the expression was matched. mmaattcchhIInnffoo is local to the top level of the match command unless declared global at that level by the Tcl gglloobbaall command. If it is to be used as a global, it must be declared global before ssccaannffiillee is called (since ssccaannffiillee sets the mmaattcchhIInnffoo before the match code is executed, a subsequent gglloobbaall will override the local variable). The following array entries are available: mmaattcchhIInnffoo((lliinnee)) Contains the text of the line of the file that was matched. mmaattcchhIInnffoo((ooffffsseett)) The byte offset into the file of the first character of the line that was matched. mmaattcchhIInnffoo((lliinneennuumm)) The line number of the line that was matched. This is relative to the first line scanned, which is usually, but not necessarily, the first line of the file. The first line is line number one. mmaattcchhIInnffoo((ccoonntteexxtt))

The context handle of the context that this scan is asso-

ciated with. mmaattcchhIInnffoo((hhaannddllee)) The file id (handle) of the file currently being scanned. mmaattcchhIInnffoo((ccooppyyHHaannddllee))

The file id (handle) of the file specified by the -ccooppyy-

ffiillee option. The element does not exist if -ccooppyyffiillee was

not specified. mmaattcchhIInnffoo((ssuubbmmaattcchh00))

Will contain the characters matching the first parenthe-

sized subexpression. The second will be contained in ssuubbmmaattcchh11, etc. mmaattcchhIInnffoo((ssuubbiinnddeexx00)) Will contain the a list of the starting and ending indices of the string matching the first parenthesized subexpression. The second will be contained in ssuubbiinnddeexx11, etc. All ssccaannmmaattcchh patterns that match a line will be processed in the order in which their specifications were added to the scan

context. The remainder of the ssccaannmmaattcchh pattern-command pairs

may be skipped for a file line if a ccoonnttiinnuuee is executed by the Tcl code of a preceding, matched pattern. If a rreettuurrnn is executed in the body of the match command, the ssccaannffiillee command currently in progress returns, with the value passed to rreettuurrnn as its return value. MMAATTHH CCOOMMMMAANNDDSS

Several extended math commands commands make many additional math func-

tions available in TclX. In addition, a set of procedures provide com-

mand access to the math functions supported by the eexxpprr command. The following procedures provide command interfaces to the expr math functions. They take the same arguments as the eexxpprr functions and may take expressions as arguments. aabbss aaccooss aassiinn aattaann22 aattaann cceeiill ccooss ccoosshh ddoouubbllee eexxpp fflloooorr ffmmoodd hhyyppoott iinntt lloogg1100 lloogg ppooww rroouunndd ssiinn ssiinnhh ssqqrrtt ttaann ttaannhh mmaaxx num1 ?..numN? eexxpprr mmaaxx((nnuumm11,, nnuumm22)) Returns the argument that has the highest numeric value. Each argument may be any integer or floating point value. This functionality is also available as a math function mmaaxx in the Tcl eexxpprr command. mmiinn num1 ?..numN? eexxpprr mmiinn((nnuumm11,, nnuumm22)) Returns the argument that has the lowest numeric value. Each argument may be any integer or floating point value. This functionality is also available as a math function mmiinn in the Tcl eexxpprr command. rraannddoomm limit | sseeeedd ?seedval? Generate a pseudorandom integer number greater than or equal to

zero and less than limit. If sseeeedd is specified, then the com-

mand resets the random number generator to a starting point

derived from the sseeeeddvvaall. This allows one to reproduce pseudo-

random number sequences for testing purposes. If seedval is omitted, then the seed is set to a value based on current system state and the current time, providing a reasonably interesting

and ever-changing seed.

LLIISSTT MMAANNIIPPUULLAATTIIOONN CCOOMMMMAANNDDSS

Extended Tcl provides additional list manipulation commands and proce-

dures. iinntteerrsseecctt lista listb Procedure to return the logical intersection of two lists. The returned list will be sorted. iinntteerrsseecctt33 lista listb Procedure to intersects two lists, returning a list containing three lists: The first list returned is everything in lista that wasn't in listb. The second list contains the intersection of the two lists, and the third list contains all the elements that were in listb but weren't in lista. The returned lists will be sorted. llaassssiiggnn list var ?var...? Assign successive elements of a list to specified variables. If

there are more variable names than fields, the remaining vari-

ables are set to the empty string. If there are more elements than variables, a list of the unassigned elements is returned. For example, lassign {dave 100 200 {Dave Foo}} name uid gid longName Assigns name to ``dave'', uid to ``100'', gid to ``200'', and longName to ``Dave Foo''. llccoonnttaaiinn list element

Determine if the element is a list element of list. If the ele-

ment is contained in the list, 1 is returned, otherwise, 0 is returned. lleemmppttyy list Determine if the specified list is empty. If empty, 1 is

returned, otherwise, 0 is returned. This command is an alterna-

tive to comparing a list to an empty string, however it checks for a string of all whitespaces, which is an empty list. llmmaattcchh ?mode? list pattern Search the elements of list, returning a list of all elements matching pattern. If none match, an empty list is returned. The mode argument indicates how the elements of the list are to be matched against pattern and it must have one of the following values:

-eexxaacctt The list element must contain exactly the same string as

pattern.

-gglloobb Pattern is a glob-style pattern which is matched against

each list element using the same rules as the ssttrriinngg mmaattcchh command.

-rreeggeexxpp

Pattern is treated as a regular expression and matched against each list element using the same rules as the rreeggeexxpp command.

If mode is omitted then it defaults to -gglloobb.

Only the -eexxaacctt comparison will work on binary data.

llrrmmdduuppss list Procedure to remove duplicate elements from a list. The returned list will be sorted. llvvaarrccaatt var string ?string...?

This command treats each string argument as a list and concate-

nates them to the end of the contents of var, forming a a single list. The list is stored back into var and also returned as the result. if var does not exist, it is created. llvvaarrppoopp var ?indexExpr? ?string? The llvvaarrppoopp command pops (deletes) the element indexed by the expression indexExpr from the list contained in the variable var. If index is omitted, then 0 is assumed. If string, is specified, then the deleted element is replaced by string. The replaced or deleted element is returned. Thus ``lvarpop argv 0'' returns the first element of argv, setting argv to contain the remainder of the string. If the expression indexExpr starts with the string eenndd, then eenndd is replaced with the index of the last element in the list. If the expression starts with lleenn, then lleenn is replaced with the length of the list. llvvaarrppuusshh var string ?indexExpr? The llvvaarrppuusshh command pushes (inserts) string as an element in the list contained in the variable var. The element is inserted before position indexExpr in the list. If index is omitted, then 0 is assumed. If var does not exists, it is created. If the expression indexExpr starts with the string eenndd, then eenndd is replaced with the index of the last element in the list. If the expression starts with lleenn, then lleenn is replaced with the length of the list. Note the a value of eenndd means insert the string before the last element. uunniioonn lista listb Procedure to return the logical union of the two specified lists. Any duplicate elements are removed. KKEEYYEEDD LLIISSTTSS Extended Tcl defines a special type of list referred to as keyed lists. These lists provided a structured data type built upon standard Tcl

lists. This provides a functionality similar to structs in the C pro-

gramming language. A keyed list is a list in which each element contains a key and value pair. These element pairs are stored as lists themselves, where the key is the first element of the list, and the value is the second. The

key-value pairs are referred to as fields. This is an example of a

keyed list:

{{NAME {Frank Zappa}} {JOB {musician and composer}}}

If the variable ppeerrssoonn contained the above list, then kkeeyyllggeett ppeerrssoonn

NAME ol rtr {Frank Zappa}. xctn te omn:

keylset person ID 106 would make ppeerrssoonn contain

{{ID 106} {NAME {Frank Zappa}} {JOB {musician and composer}}

Fields may contain subfields; `.' is the separator character. Sub-

fields are actually fields where the value is another keyed list. Thus

the following list has the top level fields ID and NAME, and subfields

NAME.FIRST and NAME.LAST:

{ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}

There is no limit to the recursive depth of subfields, allowing one to build complex data structures. Keyed lists are constructed and accessed via a number of commands. All keyed list management commands take the name of the variable containing the keyed list as an argument (i.e. passed by reference), rather than passing the list directly. kkeeyyllddeell listvar key Delete the field specified by key from the keyed list in the variable listvar. This removes both the key and the value from the keyed list. kkeeyyllggeett listvar ?key? ?retvar | {}? Return the value associated with key from the keyed list in the variable listvar. If retvar is not specified, then the value will be returned as the result of the command. In this case, if key is not found in the list, an error will result. If retvar is specified and key is in the list, then the value is returned in the variable retvar and the command returns 11 if the key was present within the list. If key isn't in the list, the command will return 00, and retvar will be left unchanged. If {{}} is specified for retvar, the value is not returned, allowing the Tcl programmer to determine if a key is present in a keyed list

without setting a variable as a side-effect.

If key is omitted, then a list of all the keys in the keyed list is returned. kkeeyyllkkeeyyss listvar ?key? Return the a list of the keys in the keyed list in the variable listvar. If keys is specified, then it is the name of a key field who's subfield keys are to be retrieve. kkeeyyllsseett listvar key value ?key2 value2 ...? Set the value associated with key, in the keyed list contained in the variable listvar, to value. If listvar does not exists, it is created. If key is not currently in the list, it will be added. If it already exists, value replaces the existing value. Multiple keywords and values may be specified, if desired. SSTTRRIINNGG AANNDD CCHHAARRAACCTTEERR MMAANNIIPPUULLAATTIIOONN CCOOMMMMAANNDDSS The commands provide additional functionality to classify characters, convert characters between character and numeric values, index into a string, determine the length of a string, extract a range of character from a string, replicate a string a number of times, and transliterate a string (similar to the Unix tr program).

ccccoollllaattee ?-local? string1 string2

This command compares two strings. If returns -11 if string1 is

less than string2, 00 if they are equal and 11 if string1 is greater than string2.

If -llooccaall is specified, the strings are compared according to

the collation environment of the current locale. This command does not work with binary or UTF data. ccccoonnccaatt ?string1? ?string2? ?...? Concatenate the arguments, returning the resulting string. While string concatenation is normally performed by the parser, it is occasionally useful to have a command that returns a string. The is generally useful when a command to evaluate is required. No separators are inserted between the strings.

This command is UTF-aware.

cceeqquuaall string string This command compares two strings for equality. It returns 11 if string1 and string2 are the identical and 00 if they are not.

This command is a short-cut for ssttrriinngg ccoommppaarree and avoids the

problems with string expressions being treated unintentionally as numbers.

This command is UTF-aware and will also work on binary data.

cciinnddeexx string indexExpr Returns the character indexed by the expression indexExpr (zero based) from string. If the expression indexExpr starts with the string eenndd, then eenndd is replaced with the index of the last character in the string. If the expression starts with lleenn, then lleenn is replaced with the length of the string.

This command is UTF-aware.

cclleennggtthh string Returns the length of string in characters. This command is a shortcut for: string length string

This command is UTF-aware.

ccrraannggee string firstExpr lastExpr

Returns a range of characters from string starting at the char-

acter indexed by the expression firstExpr (zero-based) until the

character indexed by the expression lastExpr. If the expression firstExpr or llaassttEExxpprr starts with the string eenndd, then eenndd is replaced with the index of the last character in the string. If the expression starts with lleenn, then lleenn is replaced with the length of the string.

This command is UTF-aware.

ccssuubbssttrr string firstExpr lengthExpr

Returns a range of characters from string starting at the char-

acter indexed by the expression firstExpr (zero-based) for

lengthExpr characters. If the expression firstExpr or lleennggtthhEExxpprr starts with the string eenndd, then eenndd is replaced with the index of the last character in the string. If the expression starts with lleenn, then lleenn is replaced with the length of the string.

This command is UTF-aware.

ccttookkeenn strvar separators Parse a token out of a character string. The string to parse is contained in the variable named strvar. The string separators contains all of the valid separator characters for tokens in the string. All leading separators are skipped and the first token is returned. The variable strvar will be modified to contain the remainder of the string following the token. This command does not work with binary data.

ccttyyppee ?-failindex var? class string

ccttyyppee determines whether all characters in string are of the specified class. It returns 11 if they are all of class, and 00 if they are not, or if the string is empty. This command also provides another method (besides ffoorrmmaatt and ssccaann) of converting between an ASCII character and its numeric value. The following ccttyyppee commands are available:

ccttyyppee ?-failindex var? alnum string

Tests that all characters are alphabetic or numeric char-

acters as defined by the character set.

ccttyyppee ?-failindex var? alpha string

Tests that all characters are alphabetic characters as defined by the character set.

ccttyyppee ?-failindex var? ascii string

Tests that all characters are an ASCII character (a non-

negative number less than 0200). ccttyyppee cchhaarr number

Converts the numeric value, string, to an ASCII charac-

ter. Number must be in the range 0 through the maximum Unicode values.

ccttyyppee ?-failindex var? cntrl string

Tests that all characters are ``control characters'' as defined by the character set.

ccttyyppee ?-failindex var? digit string

Tests that all characters are valid decimal digits, i.e. 0 through 9.

ccttyyppee ?-failindex var? graph string

Tests that all characters within are any character for which ctype print is true, except for space characters.

ccttyyppee ?-failindex var? lower string

Tests that all characters are lowercase letters as defined by the character set. ccttyyppee oorrdd character Convert a character into its decimal numeric value. The first character of the string is converted to its numeric Unicode value.

ccttyyppee ?-failindex var? space string

Tests that all characters are either a space, horizontal-

tab, carriage return, newline, vertical-tab, or form-

feed.

ccttyyppee ?-failindex var? print string

Tests that all characters are a space or any character for which ctype alnum or ctype punct is true or other ``printing character'' as defined by the character set.

ccttyyppee ?-failindex var? punct string

Tests that all characters are made up of any of the char-

acters other than the ones for which aallnnuumm, ccnnttrrll, or ssppaaccee is true.

ccttyyppee ?-failindex var? upper string

Tests that all characters are uppercase letters as defined by the character set.

ccttyyppee ?-failindex var? xdigit string

Tests that all characters are valid hexadecimal digits, that is 0 through 9, a through f or A through F.

If -failindex is specified, then the index into string of the

first character that did not match the class is returned in var. rreepplliiccaattee string countExpr Returns string, replicated the number of times indicated by the expression countExpr.

This command is UTF-aware and will work with binary data.

ttrraannsslliitt inrange outrange string Translate characters in string, changing characters occurring in inrange to the corresponding character in outrange. Inrange and

outrange may be list of characters or a range in the form `A-M'.

For example:

translit a-z A-Z foobar

This command currently only supports characters in ASCII range; UTF-8 characters

out of this range will generate an error. XXPPGG//33 MMEESSSSAAGGEE CCAATTAALLOOGG CCOOMMMMAANNDDSS These commands provide a Tcl interface to message catalogs that are compliant with the X/Open Portability Guide, Version 3 (XPG/3). Tcl programmers can use message catalogs to create applications that

are language-independent. Through the use of message catalogs,

prompts, messages, menus and so forth can exist for any number of lan-

guages, and they can altered, and new languages added, without affect-

ing any Tcl or C source code, greatly easing the maintenance difficul-

ties incurred by supporting multiple languages. A default text message is passed to the command that fetches entries

from message catalogs. This allows the Tcl programmer to create mes-

sage catalogs containing messages in various languages, but still have a set of default messages available regardless of the presence of any message catalogs, and allow the programs to press on without difficulty when no catalogs are present. Thus, the normal approach to using message catalogs is to ignore errors on ccaattooppeenn, in which case ccaattggeettss will return the default message that was specified in the call. The Tcl message catalog commands normally ignore most errors. If it is

desirable to detect errors, a special option is provided. This is nor-

mally used only during debugging, to insure that message catalogs are being used. If your Unix implementation does not have XPG/3 message catalog support, stubs will be compiled in that will create a version of ccaattggeettss that always returns the default string. This allows for easy porting of software to environments that don't have support for message catalogs.

Message catalogs are global to the process, an application with multi-

ple Tcl interpreters within the same process may pass and share message catalog handles.

ccaattooppeenn ?-ffaaiill | -nnooffaaiill? catname

Open the message catalog catname. This may be a relative path name, in which case the NNLLSSPPAATTHH environment variable is searched to find an absolute path to the message catalog. A handle in the form mmssggccaattN is returned. Normally, errors are ignored, and in the case of a failed call to ccaattooppeenn, a handle is returned to an unopened message catalog. (This handle may still be passed to ccaattggeettss and ccaattcclloossee, causing ccaattggeettss to simply return the

default string, as described above. If the -ffaaiill option is

specified, an error is returned if the open fails. The option

-nnooffaaiill specifies the default behavior of not returning an error

when ccaattooppeenn fails to open a specified message catalog. If the handle from a failed ccaattooppeenn is passed to ccaattggeettss, the default string is returned. ccaattggeettss catHandle setnum msgnum defaultstr Retrieve a message form a message catalog. CatHandle should be a Tcl message catalog handle that was returned by ccaattooppeenn. Setnum is the message set number, and msgnum is the message number. If

the message catalog was not opened, or the message set or mes-

sage number cannot be found, then the default string, default-

str, is returned.

ccaattcclloossee ?-ffaaiill | -nnooffaaiill? cathandle

Close the message catalog specified by cathandle. Normally,

errors are ignored. If -ffaaiill is specified, any errors closing

the message catalog file are returned. The option -nnooffaaiill spec-

ifies the default behavior of not returning an error. The use

of -ffaaiill only makes sense if it was also specified in the call

to ccaattooppeenn. mmaaiinnlloooopp

This procedure sets up a top-level event loop. Events are pro-

cessed until there are no more active event sources, at which

time the process exits. It is used to build event oriented pro-

grams using the TclX shell in a style similar to that used with

wwiisshh. If the global variable ttcclliinntteerraaccttiivvee exists and has a true value an interactive command handler is started as well. If the command handler is terminated by an EOF, the process will be exited. HHEELLPP FFAACCIILLIITTYY The help facility allows one to look up help pages which where extracted from the standard Tcl manual pages and Tcl scripts during Tcl

installation. Help files are structured as a multilevel tree of sub-

jects and help pages. Help files are found by searching directories named hheellpp in the directories listed in the aauuttooppaatthh variable. All of the files in the list of help directories form a virtual root of the help tree. This method allows multiple applications to provide help trees without having the files reside in the same directory. The help facility can be accessed in two ways, as interactive commands

in the Extended Tcl shell or as an interactive Tk-based program (if you

have built Extended Tcl with Tk).

To run the Tk-based interactive help program:

tclhelp ?addpaths? Where addpaths are additional paths to search for help directories. By default, only the autopath used by ttccllhheellpp is search. This will result in help on Tcl, Extended Tcl and Tk. The following interactive Tcl commands and options are provided with the help package: hheellpp Help, without arguments, lists of all the help subjects and pages under the current help subject. hheellpp subject Displays all of help pages and lower level subjects (if any exist) under the subject subject. hheellpp subject/helppage Display the specified help page. The help output is passed

through a simple pager if output exceeds 23 lines, pausing wait-

ing for a return to be entered. If any other character is entered, the output is terminated. hheellppccdd ?subject? Change the current subject, which is much like the Unix current

directory. If subject is not specified, return to the top-level

of the help tree. Help subject path names may also include ``..'' elements. hheellppppwwdd Displays the current help subject. hheellpp help | ? Displays help on the help facility at any directory level. aapprrooppooss pattern

This command locates subjects by searching their one-line

descriptions for a pattern. Apropos is useful when you can remember part of the name or description of a command, and want

to search through the one-line summaries for matching lines.

Full regular expressions may be specified (see the rreeggeexxpp com-

mand). TTCCLL LLOOAADDAABBLLEE LLIIBBRRAARRIIEESS AANNDD PPAACCKKAAGGEESS Extended Tcl supports standard Tcl ttccllIInnddeexx libraries and package libraries. A package library file can contain multiple independent Tcl packages. A package is a named collection of related Tcl procedures and initialization code. The package library file is just a regular Unix text file, editable with your favorite text editor, containing packages of Tcl source code. The package library file name must have the suffix ..ttlliibb. An index file with the same prefix name and the suffix ..ttnnddxx resides the same directory as the ..ttlliibb file. The ..ttnnddxx will be automatically created whenever it is out of date or missing (provided there is write access to the directory). The variable aauuttooppaatthh contains a list of directories that are searched for libraries. The first time an unknown command trap is take, the indexes for the libraries are loaded into memory. If the aauuttooppaatthh

variable is changed during execution of a program, it will be re-

searched. Only the first package of a given name found during the exe-

cution of a program is loaded. This can be overridden with llooaaddllii-

bbiinnddeexx command. The start of a package is delimited by:

##@@ppaacckkaaggee: packagename proc1 ?..procN?

These lines must start in column one. Everything between the ##@@ppaacckk-

aaggee:: keyword and the next ##@@ppaacckkaaggee:: keyword or a ##@@ppaacckkeenndd keyword, or

the end of the file, becomes part of the named package. The specified procedures, proc1..procN, are the entry points of the package. When a command named in a package specification is executed and detected as an unknown command, all code in the specified package will be sourced. This package should define all of the procedures named on the package line, define any support procedures required by the package and do any

package-specific initialization. Packages declarations maybe continued

on subsequent lines using standard Tcl backslash line continuations.

The ##@@ppaacckkeenndd keyword is useful to make sure only the minimum required

section of code is sourced. Thus for example a large comment block at the beginning of the next file won't be loaded. Care should be taken in defining packagename, as the first package found in the path by with a given name is loaded. This can be useful in developing new version of packages installed on the system. For example, in a package source file, the presence of the following line:

##@@ppaacckkaaggee:: ddiirreeccttoorryyssttaacckk ppuusshhdd ppooppdd ddiirrss

says that the text lines following that line in the package file up to

the next package line or the end of the file is a package named ddiirreecc-

ttoorryyssttaacckk and that an attempt to execute either pushd, popd or dirs when the routine is not already defined will cause the ddiirreeccttoorryyssttaacckk portion of the package file to be loaded. PPAACCKKAAGGEE LLIIBBRRAARRYY MMAANNAAGGEEMMEENNTT CCOOMMMMAANNDDSS Several commands are available for building and managing package libraries. Commands that are extended versions of the standard Tcl

library commands are listed here. All of the standard Tcl library man-

agement commands and variables are also supported.

aauuttooccoommmmaannddss ?-llooaaddeerrss?

Lists the names of all known loadable procedures and commands

procedures. If -llooaaddeerrss is specified, the command that will be

executed to load the command will also be returned. bbuuiillddppaacckkaaggeeiinnddeexx libfilelist

Build index files for package libraries. The argument lib-

filelist is a list of package libraries. Each name must end with the suffix ..ttlliibb. A corresponding ..ttnnddxx file will be

built. The user must have write access to the directory con-

taining each library. ccoonnvveerrttlliibb tclIndex packagelib ?ignore? Convert a Ousterhout style tclIndex index file and associate source files into a package library ppaacckkaaggeelliibb. If ppaacckkaaggeelliibb does not have a ..ttlliibb extension, one will be added. Any files specified in tclIndex that are in the list ignore will be skipped. Files listed in ignore should just be the base file names, not full paths. llooaaddlliibbiinnddeexx libfile.tlib Load the package library index of the library file lliibbffiillee (which must have the suffix .tlib). Package library indexes along the aauuttooppaatthh are loaded automatically on the first ddeemmaannddllooaadd; this command is provided to explicitly load libraries that are not in the path. If the index file (with a .tndx suffix) does not exists or is out of date, it will be rebuilt if the user has directory permissions to create it. If a package with the same name as a package in libfile.tlib has already been loaded, its definition will be overridden by the new package. However, if any procedure has actually been used

from the previously defined package, the procedures from lib-

file.tlib will not be loaded.

aauuttooppaacckkaaggeess ?-location?

Returns a list of the names of all defined packages. If -loca-

tion is specified, a list of pairs of package name and the ..ttlliibb path name, offset and length of the package within the library. aauuttoollooaaddffiillee file Source a file, as with the ssoouurrccee command, except search aauuttooppaatthh for the file. sseeaarrcchhppaatthh path file Search all directories in the specified path, which is a Tcl list, for the specified file. Returns the full path name of the file, or an empty string if the requested file could not be found.