home *** CD-ROM | disk | FTP | other *** search
Text File | 1998-10-30 | 153.9 KB | 2,707 lines
TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) NNNNAAAAMMMMEEEE TclX - Extended Tcl: Extended command set for Tcl IIIINNNNTTTTRRRROOOODDDDUUUUCCCCTTTTIIIIOOOONNNN This man page contains the documentation for all of the extensions that are added to Tcl 7.4 by Extended Tcl (TclX 7.4a). These extensions increase Tcl's capabilities by adding new commands to it, without changing the syntax of standard Tcl. Extended Tcl is a superset of standard Tcl and is built alongside the standard Tcl sources. Extended Tcl has three basic functional areas: A set of new commands, a Tcl shell (i.e. a Unix shell-style command line and interactive environment), 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 TCP/IP Server Access o File Scanning Commands o Math Commands o List Maninipulation Commands o Keyed Lists o String and Character Manipulation Commands o XPG/3 Message Catalog Commands o Extended Tcl Shell o Help Facility o Tcl Loadable Libraries and Packages GGGGEEEENNNNEEEERRRRAAAALLLL CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS 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. ddddiiiirrrrssss This procedure lists the directories in the directory stack. PPPPaaaaggggeeee 1111 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) ccccoooommmmmmmmaaaannnnddddlllloooooooopppp ?_p_r_o_m_p_t_1? ?_p_r_o_m_p_t_2? Create an interactive command loop for the current TCL interpreter. This command receives commands from stdin and executes them. It is useful TCL scripts that do not normally converse interactively with a user through a Tcl command interpreter, but which sometimes want to enter this mode. _P_r_o_m_p_t_1 is a Tcl command that is evaluated to output a prompt string. The old value of ttttccccllll____pppprrrroooommmmpppptttt1111 is saved and it is set to this value for the duration of the command loop. _P_r_o_m_p_t_2 is a command that is evaluated to output the ``downlevel prompt'', which is the prompt which is issued for continuation input. The old value of ttttccccllll____pppprrrroooommmmpppptttt2222 is saved and it is set to this value for the duration of the command loop. When the command terminates, the variables for the prompt hooks will be set to their old value. If these arguments are not specified, the prompt hooks use their current value. eeeecccchhhhoooo ?_s_t_r ...? Writes zero or more strings to standard output, followed by a newline. iiiinnnnffffooooxxxx _o_p_t_i_o_n Return information about Extended Tcl, or the current application. The following iiiinnnnffffooooxxxx command options are available: vvvveeeerrrrssssiiiioooonnnn 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 a letter indicating the version of Extended Tcl being used. This is the documentation for version 7777....4444aaaa. ppppaaaattttcccchhhhlllleeeevvvveeeellll Return the patchlevel for Extended Tcl. hhhhaaaavvvveeee____ffffcccchhhhoooowwwwnnnn Return 1111 if the ffffcccchhhhoooowwwwnnnn system call is available. This supports the ----ffffiiiilllleeeeiiiidddd option on the cccchhhhoooowwwwnnnn and cccchhhhggggrrrrpppp commands. hhhhaaaavvvveeee____ffffcccchhhhmmmmoooodddd Return 1111 if the ffffcccchhhhmmmmoooodddd system call is available. This supports the ----ffffiiiilllleeeeiiiidddd option on the cccchhhhmmmmoooodddd command. hhhhaaaavvvveeee____fffflllloooocccckkkk Return 1111 if the fffflllloooocccckkkk command defined, 0000 if it is not available. hhhhaaaavvvveeee____ffffssssyyyynnnncccc Return 1111 if the ffffssssyyyynnnncccc system call is available and the ssssyyyynnnncccc command will sync individual files. 0000 if it is not available PPPPaaaaggggeeee 2222 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) and the ssssyyyynnnncccc command will always sync all file buffers. hhhhaaaavvvveeee____ffffttttrrrruuuunnnnccccaaaatttteeee Return 1111 if the ffffttttrrrruuuunnnnccccaaaatttteeee system call is available. If it is, the ffffttttrrrruuuunnnnccccaaaatttteeee command ----ffffiiiilllleeeeiiiidddd option maybe used. hhhhaaaavvvveeee____mmmmssssggggccccaaaattttssss Return 1111 if XPG message catalogs are available, 0000 if they are not. The ccccaaaattttggggeeeettttssss is designed to continue to function without message catalogs, always returning the default string. hhhhaaaavvvveeee____ppppoooossssiiiixxxx____ssssiiiiggggnnnnaaaallllssss Return 1111 if Posix signals are available (bbbblllloooocccckkkk and uuuunnnnbbbblllloooocccckkkk options available for the signal command). 0000 is returned if Posix signals are not available. hhhhaaaavvvveeee____ssssoooocccckkkkeeeettttssss Return 1111 if sockets are available (sssseeeerrrrvvvveeeerrrr____**** suite and ffffssssttttaaaatttt llllooooccccaaaallllhhhhoooosssstttt and rrrreeeemmmmooootttteeeehhhhoooosssstttt options). 0000 is returned if sockets are not available. hhhhaaaavvvveeee____ttttrrrruuuunnnnccccaaaatttteeee Return 1111 if the ttttrrrruuuunnnnccccaaaatttteeee of cccchhhhssssiiiizzzzeeee system call is available. If it is, the ffffttttrrrruuuunnnnccccaaaatttteeee command will work. aaaappppppppnnnnaaaammmmeeee Return the symbolic application name of the current application linked with the Extended Tcl library. The C variable ttttccccllllAAAAppppppppNNNNaaaammmmeeee must be set by the application to return an application specific value for this variable. aaaapppppppplllloooonnnnggggnnnnaaaammmmeeee Return a natural language name for the current application. The C variable ttttccccllllLLLLoooonnnnggggAAAAppppppppNNNNaaaammmmeeee must be set by the application to return an application specific value for this variable. aaaappppppppvvvveeeerrrrssssiiiioooonnnn Return the version number for the current application. The C variable ttttccccllllAAAAppppppppVVVVeeeerrrrssssiiiioooonnnn must be set by the application to return an application-specific value for this variable. aaaappppppppppppaaaattttcccchhhhlllleeeevvvveeeellll Return the patchlevel for the current application. The C variable ttttccccllllAAAAppppppppPPPPaaaattttcccchhhhlllleeeevvvveeeellll must be set by the application to return an application-specific value for this variable. ffffoooorrrr____aaaarrrrrrrraaaayyyy____kkkkeeeeyyyyssss _v_a_r _a_r_r_a_y__n_a_m_e _c_o_d_e This procedure performs a foreach-style loop for each key in the named array. The bbbbrrrreeeeaaaakkkk and ccccoooonnnnttttiiiinnnnuuuueeee statements work as with ffffoooorrrreeeeaaaacccchhhh. PPPPaaaaggggeeee 3333 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) ffffoooorrrr____rrrreeeeccccuuuurrrrssssiiiivvvveeee____gggglllloooobbbb _v_a_r _d_i_r_l_i_s_t _g_l_o_b_l_i_s_t _c_o_d_e This procedure performs a foreach-style loop over recursively matched files. All directories in _d_i_r_l_i_s_t are recursively searched (breadth-first), comparing each file found against the file glob patterns in gggglllloooobbbblllliiiisssstttt. For each matched file, the variable _v_a_r is set to the file path and _c_o_d_e is evaluated. Symbolic links are not followed. lllloooooooopppp _v_a_r _f_i_r_s_t _l_i_m_i_t ?_i_n_c_r_e_m_e_n_t? _b_o_d_y LLLLoooooooopppp is a looping command, similar in behavior to the Tcl ffffoooorrrr statement, except that the lllloooooooopppp 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 _v_a_r argument is the name of a Tcl variable that will contain the loop index. The loop index is set to the value specified by _f_i_r_s_t. The Tcl interpreter is invoked upon _b_o_d_y zero or more times, where _v_a_r is incremented by _i_n_c_r_e_m_e_n_t every time through the loop, or by one if _i_n_c_r_e_m_e_n_t is not specified. _I_n_c_r_e_m_e_n_t can be negative in which case the loop will count downwards. When _v_a_r reaches _l_i_m_i_t, the loop terminates without a subsequent execution of _b_o_d_y. For instance, if the original lllloooooooopppp parameters would cause lllloooooooopppp to terminate, say _f_i_r_s_t was one, _l_i_m_i_t was zero and _i_n_c_r_e_m_e_n_t was not specified or was non-negative, _b_o_d_y is not executed at all and lllloooooooopppp returns. The _f_i_r_s_t, _l_i_m_i_t and _i_n_c_r_e_m_e_n_t are integer expressions. They are only evaulated once at the beginning of the loop. If a ccccoooonnnnttttiiiinnnnuuuueeee command is invoked within _b_o_d_y then any remaining commands in the current execution of _b_o_d_y are skipped, as in the ffffoooorrrr command. If a bbbbrrrreeeeaaaakkkk command is invoked within _b_o_d_y then the lllloooooooopppp command will return immediately. LLLLoooooooopppp returns an empty string. ppppooooppppdddd This procedure pops the top directory entry from the directory stack and make it the current directory. ppppuuuusssshhhhdddd ?_d_i_r? This procedure pushs the current directory onto the directory stack and ccccdddd to the specified directory. If the directory is not specified, then the current directory is pushed, but remains unchanged. rrrreeeeccccuuuurrrrssssiiiivvvveeee____gggglllloooobbbb _d_i_r_l_i_s_t _g_l_o_b_l_i_s_t This procedure returns a list of recursively matches files. All directories in _d_i_r_l_i_s_t are recursively searched (breadth-first), comparing each file found against the file glob patterns in gggglllloooobbbblllliiiisssstttt. Symbolic links are not followed. PPPPaaaaggggeeee 4444 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) sssshhhhoooowwwwpppprrrroooocccc ?_p_r_o_c_n_a_m_e ...? 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. This section contains information on commands and procdures that are useful for developing and debugging Tcl scripts. ccccmmmmddddttttrrrraaaacccceeee _l_e_v_e_l|oooonnnn ?nnnnooooeeeevvvvaaaallll? ?nnnnoooottttrrrruuuunnnnccccaaaatttteeee? ?_p_r_o_c_s? ?_f_i_l_e_i_d? Print a trace statement for all commands executed at depth of _l_e_v_e_l or below (1 is the top level). If oooonnnn is specified, all commands at any level are traced. The following options are available: nnnnooooeeeevvvvaaaallll Causes arguments to be printed unevaluated. If nnnnooooeeeevvvvaaaallll 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. nnnnoooottttrrrruuuunnnnccccaaaatttteeee Disables the truncation of commands and evaluated arguments. pppprrrrooooccccssss 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 pppprrrrooooccccssss option is specified. This option is particularly useful for greatly reducing the output of ccccmmmmddddttttrrrraaaacccceeee while debugging. ffffiiiilllleeeeiiiidddd This is a file id as returned by the ooooppppeeeennnn 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 monitored externally or provide useful information for debugging problems that cause core dumps. 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: PPPPaaaaggggeeee 5555 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) cmdtrace on [open cmd.log w] ccccmmmmddddttttrrrraaaacccceeee ooooffffffff Turn off all tracing. ccccmmmmddddttttrrrraaaacccceeee ddddeeeepppptttthhhh Returns the current maximum trace level, or zero if trace is disabled. eeeeddddpppprrrrooooccccssss ?_p_r_o_c...? 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 EEEEDDDDIIIITTTTOOOORRRR environment variable, or vvvviiii if none is specified), then sources the file back in if it was changed. pppprrrrooooffffiiiilllleeee ????----ccccoooommmmmmmmaaaannnnddddssss???? oooonnnn pppprrrrooooffffiiiilllleeee ooooffffffff _a_r_r_a_y_V_a_r 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 procedure call stack, this allows determination of how much time is spent in a particular procedure in each of it's calling contexts. The oooonnnn option enables profile data collection. If the ----ccccoooommmmmmmmaaaannnnddddssss option is specifed, data on all commands within a procedure is collected as well a procedures. Multiple occurrences of a command within a procedure are not distinguished, but this data may still be useful for analysis. The ooooffffffff option turns off profiling and moves the data collected to the array _a_r_r_a_y_V_a_r. The array is address by a list containing 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 (and all procedures it called). The list is in the form {_c_o_u_n_t _r_e_a_l _c_p_u}. A Tcl procedure pppprrrrooooffffrrrreeeepppp is supplied for reducing the data and producing a report pppprrrrooooffffrrrreeeepppp _p_r_o_f_D_a_t_a_V_a_r _s_o_r_t_K_e_y ?_o_u_t_F_i_l_e? ?_u_s_e_r_T_i_t_l_e? This procedure generates a report from data collect from the profile command. PPPPrrrrooooffffDDDDaaaattttaaaaVVVVaaaarrrr is the name of the array containing the data returned by the pppprrrrooooffffiiiilllleeee command. SSSSoooorrrrttttKKKKeeeeyyyy indicates which data value to sort by. It should be one of "ccccaaaallllllllssss", "ccccppppuuuu" or "rrrreeeeaaaallll". OOOOuuuuttttFFFFiiiilllleeee is the name of file to write the report to. If omitted, stdout is assumed. UUUUsssseeeerrrrTTTTiiiittttlllleeee is an optional title line to add to output. ssssaaaavvvveeeepppprrrrooooccccssss _f_i_l_e_N_a_m_e ?_p_r_o_c...? This prodcure saves the definition of the named procedure, or all currently defined procedures if none is specified, to the named PPPPaaaaggggeeee 6666 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) file. UUUUNNNNIIIIXXXX AAAACCCCCCCCEEEESSSSSSSS CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS 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. aaaallllaaaarrrrmmmm _s_e_c_o_n_d_s Instructs the system to send a SIGALRM signal in the specified number of seconds. This is a floating point number, so fractions of a section may be specified. If _s_e_c_o_n_d_s 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 sssseeeettttiiiittttiiiimmmmeeeerrrr system call, _s_e_c_o_n_d_s is rounded up to an integer number of seconds. ccccoooonnnnvvvveeeerrrrttttcccclllloooocccckkkk _d_a_t_e_S_t_r_i_n_g ?GGGGMMMMTTTT|{}? ?_b_a_s_e_C_l_o_c_k? Convert _d_a_t_e_S_t_r_i_n_g to an integer clock value (see ggggeeeettttcccclllloooocccckkkk). This command can parse and convert virtually any standard date and/or time string, which can include standard time zone mnemonics. If only a time is specified, the current date is assumed. If the string does not contain a time zone mnemonic, the local time zone is assumed, unless the GGGGMMMMTTTT argument is specified, in which case the clock value is calculated assuming that the specified time is relative to Greenwich Mean Time. If _b_a_s_e_C_l_o_c_k is specified, it should contain an integer clock value. Only the date in this value is used, not the time. This is useful for determining the time on a specific day or doing other date- relative conversions. The character string consists of zero or more specifications of the following form: _t_i_m_e - A time of day, which is of the form _h_h[:_m_m[:_s_s]] [_m_e_r_i_d_i_a_n] [_z_o_n_e] or _h_h_m_m [_m_e_r_i_d_i_a_n] [_z_o_n_e]. If no meridian is specified, _h_h is interpreted on a 24-hour clock. _d_a_t_e - A specific month and day with optional year. The acceptable formats are _m_m/_d_d[/_y_y], _m_o_n_t_h_n_a_m_e _d_d[, _y_y], _d_d _m_o_n_t_h_n_a_m_e [_y_y], and _d_a_y, _d_d _m_o_n_t_h_n_a_m_e _y_y. The default year is the current year. If the year is less then 100, then 1900 is added to it. _r_e_l_a_t_i_v_e _t_i_m_e - A specification relative to the current time. The format is _n_u_m_b_e_r _u_n_i_t; acceptable units are _y_e_a_r, _f_o_r_t_n_i_g_h_t, _m_o_n_t_h, _w_e_e_k, _d_a_y, _h_o_u_r, _m_i_n_u_t_e (or _m_i_n), and _s_e_c_o_n_d (or _s_e_c). The unit can be specified as a singular or plural, as in _3 _w_e_e_k_s. These modifiers may also be specified: _t_o_m_o_r_r_o_w, _y_e_s_t_e_r_d_a_y, _t_o_d_a_y, _n_o_w, _l_a_s_t, _t_h_i_s, _n_e_x_t, _a_g_o. The actual date is calculated according to the following steps. First, any absolute date and/or time is processed and converted. PPPPaaaaggggeeee 7777 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) Using that time as the base, day-of-week specifications are added. Next, relative specifications are used. If a date or day is specified, and no absolute or relative time is given, midnight is used. Finally, a correction is applied so that the correct hour of the day is produced after allowing for daylight savings time differences. _c_o_n_v_e_r_t_c_l_o_c_k ignores case when parsing all words. The names of the months and days of the week can be abbreviated to their first three letters, with optional trailing period. Periods are ignored in any timezone or meridian values. Note that _c_o_n_v_e_r_t_c_l_o_c_k will convert symbolic time-zone names, but these are not standardized and there are conflicts with various parts of the world. Use GMT when trying to produce a portable time that can then be converted back to a numeric value. The only dates in the range 1902 and 2037 may be converted. Some examples are: convertclock "14 Feb 92" convertclock "Feb 14, 1992 12:20 PM PST" convertclock "12:20 PM Feb 14, 1992" eeeexxxxeeeeccccllll ?----aaaarrrrggggvvvv0000 argv0? _p_r_o_g ?_a_r_g_l_i_s_t? Do an execl, replacing the current program (either Extended Tcl or an application with Extended Tcl embedded into it) with _p_r_o_g and passing the arguments in the list _a_r_g_l_i_s_t. The ----aaaarrrrggggvvvv0000 options specifies that _a_r_g_v_0 is to be passed to the program as argv [0] rather than _p_r_o_g. Note: If you are using eeeexxxxeeeeccccllll in a Tk application and it fails, you may not do anything that accesses the X server or you will receive a BBBBaaaaddddWWWWiiiinnnnddddoooowwww error from the X server. This includes executing the Tk version of the eeeexxxxiiiitttt command. We suggest using the following command to abort Tk applications after an eeeexxxxeeeeccccllll failure: kill [id process] ffffmmmmttttcccclllloooocccckkkk _c_l_o_c_k_v_a_l ?_f_o_r_m_a_t? ?GGGGMMMMTTTT||||{{{{}}}}? Converts a Unix integer time value, typically returned by ggggeeeettttcccclllloooocccckkkk, ccccoooonnnnvvvveeeerrrrttttcccclllloooocccckkkk, or the aaaattttiiiimmmmeeee, mmmmttttiiiimmmmeeee, or ccccttttiiiimmmmeeee options of the ffffiiiilllleeee command, to human-readable form. The _f_o_r_m_a_t argument is a string that describes how the date and time are to be formatted. Field descriptors consist of a ``%'' followed by a field descriptor character. All other characters are copied into the result. Valid field descriptors are: %% - Insert a %. %a - Abbreviated weekday name. %A - Full weekday name PPPPaaaaggggeeee 8888 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) %b - Abbreviated month name. %B - Full month name. %d - Day of month (01 - 31). %D - Date as %m/%d/%y. %e - Day of month (1-31), no leading zeros. %h - Abbreviated month name. %H - Hour (00 - 23). %I - Hour (00 - 12). %j - Day number of year (001 - 366). %m - Month number (01 - 12). %M - Minute (00 - 59). %n - Insert a new line. %p - AM or PM. %r - Time as %I:%M:%S %p. %R - Time as %H:%M. %S - Seconds (00 - 59). %t - Insert a tab. %T - Time as %H:%M:%S. %U - Week number of year (01 - 52), Sunday is the first day of the week. %w - Weekday number (Sunday = 0). %W - Week number of year (01 - 52), Monday is the first day of the week. %x - Local specific date format. %X - Local specific time format. %y - Year within century (00 - 99). %Y - Year as ccyy (e.g. 1990) %Z - Time zone name. If format is not specified, "%a %b %d %H:%M:%S %Z %Y" is used. If GGGGMMMMTTTT is specified, the time will be formated as Greenwich Mean Time. If the argument is not specified or is empty, then the local timezone will be used as defined by the operating environment. cccchhhhrrrrooooooootttt _d_i_r_n_a_m_e Change root directory to _d_i_r_n_a_m_e, by invoking the POSIX cccchhhhrrrrooooooootttt((((2222)))) system call. This command only succeeds if running as root. ffffoooorrrrkkkk 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 eeeexxxxeeeeccccllll is not going to be performed before the child process does output, or if a cccclllloooosssseeee and dddduuuupppp sequence is going to be performed on ssssttttddddoooouuuutttt or ssssttttddddeeeerrrrrrrr, then a fffflllluuuusssshhhh should be issued against ssssttttddddoooouuuutttt, ssssttttddddeeeerrrrrrrr and any other open output file before doing the ffffoooorrrrkkkk. Otherwise characters from the parent process pending in the buffers will be output by both the parent and child processes. Note: If you are ffffoooorrrrkkkking in a Tk based apllication you must eeeexxxxeeeeccccllll before doing any window operations in the child or you will receive PPPPaaaaggggeeee 9999 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) a BBBBaaaaddddWWWWiiiinnnnddddoooowwww error from the X server. ggggeeeettttcccclllloooocccckkkk Return the current date and time as a system-dependent integer value. The unit of the value is seconds, allowing it to be used for relative time calculations. iiiidddd ooooppppttttiiiioooonnnnssss This command provides a means of getting, setting and converting user, group and process ids. The iiiidddd command has the following options: iiiidddd uuuusssseeeerrrr ?_n_a_m_e? iiiidddd uuuusssseeeerrrriiiidddd ?_u_i_d? Set the real and effective user ID to _n_a_m_e or _u_i_d, 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. iiiidddd ccccoooonnnnvvvveeeerrrrtttt uuuusssseeeerrrriiiidddd _u_i_d iiiidddd ccccoooonnnnvvvveeeerrrrtttt uuuusssseeeerrrr _n_a_m_e Convert a user ID number to a user name, or vice versa. iiiidddd ggggrrrroooouuuupppp ?_n_a_m_e? iiiidddd ggggrrrroooouuuuppppiiiidddd ?_g_i_d? Set the real and effective group ID to _n_a_m_e or _g_i_d, 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. iiiidddd ggggrrrroooouuuuppppssss iiiidddd ggggrrrroooouuuuppppiiiiddddssss Return the current group access list of the process. The option ggggrrrroooouuuuppppssss returns group names and ggggrrrroooouuuuppppiiiiddddssss returns id numbers. iiiidddd ccccoooonnnnvvvveeeerrrrtttt ggggrrrroooouuuuppppiiiidddd _g_i_d iiiidddd ccccoooonnnnvvvveeeerrrrtttt ggggrrrroooouuuupppp _n_a_m_e Convert a group ID number to a group name, or vice versa. iiiidddd eeeeffffffffeeeeccccttttiiiivvvveeee uuuusssseeeerrrr iiiidddd eeeeffffffffeeeeccccttttiiiivvvveeee uuuusssseeeerrrriiiidddd Return the effective user name, or effective user ID number, respectively. PPPPaaaaggggeeee 11110000 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) iiiidddd eeeeffffffffeeeeccccttttiiiivvvveeee ggggrrrroooouuuupppp iiiidddd eeeeffffffffeeeeccccttttiiiivvvveeee ggggrrrroooouuuuppppiiiidddd Return the effective group name, or effective group ID number, respectively. iiiidddd eeeeffffffffeeeeccccttttiiiivvvveeee ggggrrrroooouuuuppppiiiiddddssss Return all of the groupids the user is a member of. iiiidddd hhhhoooosssstttt Return the hostname of the system the program is running on. iiiidddd pppprrrroooocccceeeessssssss Return the process ID of the current process. iiiidddd pppprrrroooocccceeeessssssss ppppaaaarrrreeeennnntttt Return the process ID of the parent of the current process. iiiidddd pppprrrroooocccceeeessssssss ggggrrrroooouuuupppp Return the process group ID of the current process. iiiidddd pppprrrroooocccceeeessssssss ggggrrrroooouuuupppp sssseeeetttt Set the process group ID of the current process to its process ID. iiiidddd hhhhoooosssstttt Returns the standard host name of the machine the process is executing on. kkkkiiiillllllll ?----ppppggggrrrroooouuuupppp? ?_s_i_g_n_a_l? _i_d_l_i_s_t Send a signal to the each process in the list _i_d_l_i_s_t, if permitted. _S_i_g_n_a_l, 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 _s_i_g_n_o is 15, SIGTERM. If ----ppppggggrrrroooouuuupppp is specified, the numbers in _i_d_l_i_s_t 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 0000 specifies the current process group. lllliiiinnnnkkkk ?----ssssyyyymmmm? _s_r_c_p_a_t_h _d_e_s_t_p_a_t_h Create a directory entry, _d_e_s_t_p_a_t_h, linking it to the existing file, _s_r_c_p_a_t_h. If ----ssssyyyymmmm is specified, a symbolic link, rather than a hard link, is created. (The ----ssssyyyymmmm option is only available on systems that support symbolic links.) mmmmkkkkddddiiiirrrr ????----ppppaaaatttthhhh???? _d_i_r_L_i_s_t Create each of the directories in the list _d_i_r_L_i_s_t. The mode on the new directories is 777, modified by the umask. If ----ppppaaaatttthhhh is specified, then any non-existent parent directories in the specified path(s) are also created. PPPPaaaaggggeeee 11111111 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) nnnniiiicccceeee ?_p_r_i_o_r_i_t_y_i_n_c_r? Change or return the process priority. If _p_r_i_o_r_i_t_y_i_n_c_r is omitted, the current priority is returned. If _p_r_i_o_r_i_t_y_i_n_c_r is positive, it is added to the current _p_r_i_o_r_i_t_y level, up to a system defined maximum (normally 11119999), Negative _p_r_i_o_r_i_t_y_i_n_c_r values cumulatively increase the program's priority down to a system defined minimum (normally ----11119999); increasing priority with negative niceness values will only work for the superuser. The new priority is returned. rrrreeeeaaaaddddddddiiiirrrr _d_i_r_P_a_t_h Returns a list containing the contents of the directory _d_i_r_P_a_t_h. The directory entries "." and ".." are not returned. rrrrmmmmddddiiiirrrr ?----nnnnooooccccoooommmmppppllllaaaaiiiinnnn? _d_i_r_L_i_s_t Remove each of the directories in the list _d_i_r_L_i_s_t. If ----nnnnooooccccoooommmmppppllllaaaaiiiinnnn is specified, then errors will be ignored. ssssiiiiggggnnnnaaaallll _a_c_t_i_o_n _s_i_g_l_i_s_t ?_c_o_m_m_a_n_d? Specify the action to take when a Unix signal is received by Extended Tcl, or a program that embeds it. _S_i_g_l_i_s_t is a list of either the symbolic or numeric Unix signal (the SIG prefix is optional). _A_c_t_i_o_n is one of the following actions to be performed on receipt of the signal. To specify all modifiable signals, use `*' (this will not include SIGKILL and SIGSTOP, as they can not be modified). ddddeeeeffffaaaauuuulllltttt - Perform system default action when signal is received (see ssssiiiiggggnnnnaaaallll system call documentation). iiiiggggnnnnoooorrrreeee - Ignore the signal. eeeerrrrrrrroooorrrr - 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: PPPPOOOOSSSSIIIIXXXX SSSSIIIIGGGG _s_i_g_n_a_m_e For the death of child signal, _s_i_g_n_a_m_e will always be SIGCHLD, rather than SIGCLD, to allow writing portable code. ttttrrrraaaapppp - When the signal occurs, execute _c_o_m_m_a_n_d and continue execution if an error is not returned by _c_o_m_m_a_n_d. The command 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 follow the standard Tcl error mechanism. Often _c_o_m_m_a_n_d will just do an eeeexxxxiiiitttt. PPPPaaaaggggeeee 11112222 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) ggggeeeetttt - 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 cosisting of the action associated with the signal, a 0000 if the signal may be delivered (not block) and a 1111 if it is blocked. The actions maybe one of `ddddeeeeffffaaaauuuulllltttt',`iiiiggggnnnnoooorrrreeee', `eeeerrrrrrrroooorrrr' or `ttttrrrraaaapppp. If the action is trap, the third element is the command associated with the action. The action `uuuunnnnkkkknnnnoooowwwwnnnn' is returned if a non-Tcl signal handler has been associated with the signal. sssseeeetttt - Set signals from a keyed list in the format returned by the ggggeeeetttt. For this action, _s_i_g_l_i_s_t is the keyed list of signal state. Signals with an action of `uuuunnnnkkkknnnnoooowwwwnnnn' are not modified. bbbblllloooocccckkkk - Block the specified signals from being received. (Posix systems only). uuuunnnnbbbblllloooocccckkkk - Allow the specified signal to be received. Pending signals will not occur. (Posix systems only). The signal action will remain enabled after the specified signal has occurred. The exception to this is SSSSIIIIGGGGCCCCHHHHLLLLDDDD on systems without Posix signals. For these systems, SSSSIIIIGGGGCCCCHHHHLLLLDDDD is not be automatically reenabled. After a SSSSIIIIGGGGCCCCHHHHLLLLDDDD signal is received, a call to wwwwaaaaiiiitttt must be performed to retrieve the exit status of the child process before issuing another ssssiiiiggggnnnnaaaallll SSSSIIIIGGGGCCCCHHHHLLLLDDDD ... 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 SSSSIIIIGGGGIIIINNNNTTTT will be set to eeeerrrrrrrroooorrrr, non-interactive Tcl sessions leave SSSSIIIIGGGGIIIINNNNTTTT unchanged from when the process started (normally ddddeeeeffffaaaauuuulllltttt for foreground processes and iiiiggggnnnnoooorrrreeee for processes in the background). sssslllleeeeeeeepppp _s_e_c_o_n_d_s Sleep the Extended Tcl process for _s_e_c_o_n_d_s seconds. ssssyyyysssstttteeeemmmm _c_o_m_m_a_n_d Executes _c_o_m_m_a_n_d via the _s_y_s_t_e_m(3) call. Differs from eeeexxxxeeeecccc in that ssssyyyysssstttteeeemmmm doesn't return the executed command's standard output as the result string, and ssssyyyysssstttteeeemmmm goes through the Unix shell to provide wildcard expansion, redirection, etc, as is normal from an sssshhhh command line. The exit code of the command is returned. ssssyyyynnnncccc ?_f_i_l_e_I_d? If _f_i_l_e_I_d is not specified, or if it is and this system does not support the _f_s_y_n_c system call, issues a _s_y_n_c system call to flush all pending disk output. If _f_i_l_e_I_d is specified and the system does support the _f_s_y_n_c system call, issues an _f_s_y_n_c on the file corresponding to the specified Tcl _f_i_l_e_I_d to force all pending output to that file out to the disk. PPPPaaaaggggeeee 11113333 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) If _f_i_l_e_I_d is specified, the file must be writable. A fffflllluuuusssshhhh will be issued against the _f_i_l_e_I_d before the sync. The _i_n_f_o_x _h_a_v_e__f_s_y_n_c command can be used to determine if "ssssyyyynnnncccc _f_i_l_e_I_d" will do a _s_y_n_c or a _f_s_y_n_c. ttttiiiimmmmeeeessss Return a list containing the process and child execution times in the form: _u_t_i_m_e _s_t_i_m_e _c_u_t_i_m_e _c_s_t_i_m_e Also see the _t_i_m_e_s(2) system call manual page. The values are in milliseconds. uuuummmmaaaasssskkkk ?_o_c_t_a_l_m_a_s_k? Sets file-creation mode mask to the octal value of _o_c_t_a_l_m_a_s_k. If _o_c_t_a_l_m_a_s_k is omitted, the current mask is returned. uuuunnnnlllliiiinnnnkkkk ?----nnnnooooccccoooommmmppppllllaaaaiiiinnnn? _f_i_l_e_l_i_s_t Delete (unlink) the files whose names are in the list _f_i_l_e_l_i_s_t. If ----nnnnooooccccoooommmmppppllllaaaaiiiinnnn is specified, then errors will be ignored. wwwwaaaaiiiitttt ?----nnnnoooohhhhaaaannnngggg? ?----uuuunnnnttttrrrraaaacccceeeedddd? ?----ppppggggrrrroooouuuupppp? ?_p_i_d? Waits for a process created with the eeeexxxxeeeeccccllll command to terminate, either due to an untrapped signal or call to _e_x_i_t system call. If the process id _p_i_d is specified, they wait on that process, otherwise wait on any child process to terminate. If ----nnnnoooohhhhaaaannnngggg is specified, then don't block waiting on a process to terminate. If no process is immediately available, return an empty list. If ----uuuunnnnttttrrrraaaacccceeeedddd 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 ----ppppggggrrrroooouuuupppp is specfied and _p_i_d is not specified, then wait on any child process whose process groupd ID is they same as the calling process. If _p_i_d is specified with ----ppppggggrrrroooouuuupppp, then it is take as a process group ID, waiting on any process in that process group to terminate. WWWWaaaaiiiitttt 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 contains the signal name. If the process is currently stopped (on systems that support SIGSTP), the second element is `STOP', followed by the signal name. Note that it is possible to wait on processes to terminate that were create in the background with the eeeexxxxeeeecccc command. However, if any other eeeexxxxeeeecccc command is executed after the process terminates, then the process status will be reaped by the eeeexxxxeeeecccc command and will not be available to the wwwwaaaaiiiitttt command. PPPPaaaaggggeeee 11114444 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) FFFFIIIILLLLEEEE CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS 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 ppppiiiippppeeee system call. Also linking and unlinking files, setting file, process, and user attributes and truncating files. An interface to the sssseeeelllleeeecccctttt 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 fffflllluuuusssshhhh command should be issued to force the data out. Alternatively, the ffffccccnnnnttttllll command may be used to set the buffering mode of a file to line-buffered or unbuffered. bbbbsssseeeeaaaarrrrcccchhhh _f_i_l_e_I_d _k_e_y ?_r_e_t_v_a_r? ?_c_o_m_p_a_r_e__p_r_o_c? Search an opened file _f_i_l_e_I_d containing lines of text sorted into ascending order for a match. _K_e_y contains the string to match. If _r_e_t_v_a_r is specified, then the line from the file is returned in _r_e_t_v_a_r, and the command returns 1111 if _k_e_y was found, and 0000 if it wasn't. If _r_e_t_v_a_r is not specified or is a null name, then the command returns the line that was found, or an empty string if _k_e_y 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 _c_o_m_p_a_r_e__p_r_o_c 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 bbbbsssseeeeaaaarrrrcccchhhh command. _C_o_m_p_a_r_e__p_r_o_c 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 _c_o_m_p_a_r_e__p_r_o_c uses to compare the key with the line, or errouenous results will occur. ccccooooppppyyyyffffiiiilllleeee ?----bbbbyyyytttteeeessss _n_u_m|----mmmmaaaaxxxxbbbbyyyytttteeeessss _n_u_m? _f_r_o_m_F_i_l_e_I_d _t_o_F_i_l_e_I_d Copies the rest of the file specified by _f_r_o_m_F_i_l_e_I_d, starting from its current position, to the file specified by _t_o_F_i_l_e_I_d, starting from its current position. If ----bbbbyyyytttteeeessss is specified, then _n_u_m bytes are copied. If less than _n_u_m bytes are available, an error is returned. If ----mmmmaaaaxxxxbbbbyyyytttteeeessss is specified, then _n_u_m bytes are copied but no error is returned if less are available. The command returns the number of bytes that were copied. The ----bbbbyyyytttteeeessss option is particularly useful for mixing binary data in with ASCII commands or data in a data stream. PPPPaaaaggggeeee 11115555 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) cccchhhhmmmmoooodddd [----ffffiiiilllleeeeiiiidddd] _m_o_d_e _f_i_l_e_l_i_s_t Set permissions of each of the files in the list _f_i_l_e_l_i_s_t to _m_o_d_e, where _m_o_d_e is an absolute numeric mode or symbolic permissions as in the UNIX cccchhhhmmmmoooodddd((((1111)))) command. To specify a mode as octal, it should be prefixed with a "0" (e.g. 0622). If the option ----ffffiiiilllleeeeiiiidddd is specified, _f_i_l_e_l_i_s_t 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 iiiinnnnffffooooxxxx hhhhaaaavvvveeee____ffffcccchhhhmmmmoooodddd command to determine if this functionallity is available. cccchhhhoooowwwwnnnn [----ffffiiiilllleeeeiiiidddd] _o_w_n_e_r|{_o_w_n_e_r _g_r_o_u_p} _f_i_l_e_l_i_s_t Set owner of each file in the list _f_i_l_e_l_i_s_t to _o_w_n_e_r, 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. _G_r_o_u_p can be a group name or numeric group id. If _g_r_o_u_p is {}, then the file group will be set to the login group of the specified user. If the option ----ffffiiiilllleeeeiiiidddd is specified, _f_i_l_e_l_i_s_t 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 iiiinnnnffffooooxxxx hhhhaaaavvvveeee____ffffcccchhhhoooowwwwnnnn command to determine if this functionallity is available. cccchhhhggggrrrrpppp [----ffffiiiilllleeeeiiiidddd] _g_r_o_u_p _f_i_l_e_l_i_s_t Set the group id of each file in the list _f_i_l_e_l_i_s_t to _g_r_o_u_p, which can be either a group name or a numeric group id. If the option ----ffffiiiilllleeeeiiiidddd is specified, _f_i_l_e_l_i_s_t 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 iiiinnnnffffooooxxxx hhhhaaaavvvveeee____ffffcccchhhhoooowwwwnnnn command to determine if this functionallity is available. dddduuuupppp _f_i_l_e_I_d ?_t_a_r_g_e_t_F_i_l_e_I_d? Duplicate an open file. A new file id is opened that addresses the same file as _f_i_l_e_I_d. If _t_a_r_g_e_t_F_i_l_e_I_d is specified, the the file is dup to this specified file id. Normally this is ssssttttddddiiiinnnn, ssssttttddddoooouuuutttt, or ssssttttddddeeeerrrrrrrr. 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 ffffccccnnnnttttllll command to set it unbuffered. If _f_i_l_e_I_d is a number rather than a Tcl file id, then the dddduuuupppp command will bind that file to a Tcl file id. This is usedful for accessing files that are passed from the parent process. The argument ?_t_a_r_g_e_t_F_i_l_e_I_d? is not valid with this operation. ffffccccnnnnttttllll _f_i_l_e_I_d _a_t_t_r_i_b_u_t_e ?_v_a_l_u_e? This command either sets or clears a file option or returns its current value. If _v_a_l_u_e are not specified, then the current value of aaaattttttttrrrriiiibbbbuuuutttteeee is returned. The following attributes may be specified: PPPPaaaaggggeeee 11116666 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) RRRRDDDDOOOONNNNLLLLYYYY - The file is opened for reading only. (Get only) WWWWRRRROOOONNNNLLLLYYYY - The file is opened for writing only. (Get only) RRRRDDDDWWWWRRRR - The file is opened for reading and writing. (Get only) RRRREEEEAAAADDDD - If the file is readable. (Get only). WWWWRRRRIIIITTTTEEEE - If the file is writable. (Get only). AAAAPPPPPPPPEEEENNNNDDDD - The file is opened for append-only writes. All writes will be forced to the end of the file. NNNNOOOONNNNBBBBLLLLOOOOCCCCKKKK - The file is to be accessed with non-blocking I/O. See the rrrreeeeaaaadddd system call for a description of how it affects the behavior of file reads. CCCCLLLLOOOOEEEEXXXXEEEECCCC - Close the file on an process exec. If the eeeexxxxeeeeccccllll command or some other mechanism causes the process to do an exec, the file will be closed if this option is set. NNNNOOOOBBBBUUUUFFFF - The file is not buffered. If set, then there no stdio buffering for the file. LLLLIIIINNNNEEEEBBBBUUUUFFFF - 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. The AAAAPPPPPPPPEEEENNNNDDDD, NNNNOOOONNNNBBBBLLLLOOOOCCCCKKKK, and CCCCLLLLOOOOEEEEXXXXEEEECCCC attributes may be set or cleared by specifying the attribute name and a value 1111 to set the attribute and 0000 to clear it. The NNNNOOOOBBBBUUUUFFFF and LLLLIIIINNNNEEEEBBBBUUUUFFFF attributes may only be set (a value of 1111) and only one of the options may be selected. Once set, it may not be changed. These options should be set before any I/O operations have been done on the file or data may be lost. fffflllloooocccckkkk _o_p_t_i_o_n_s _f_i_l_e_I_d ?_s_t_a_r_t? ?_l_e_n_g_t_h? ?_o_r_i_g_i_n? This command places a lock on all or part of the file specified by _f_i_l_e_I_d. The lock is either advisory or mandatory, depending on the mode bits of the file. The lock is placed beginning at relative byte offset _s_t_a_r_t for _l_e_n_g_t_h bytes. If _s_t_a_r_t or _l_e_n_g_t_h is omitted or empty, zero is assumed. If _l_e_n_g_t_h is zero, then the lock always extents to end of file, even if the file grows. If _o_r_i_g_i_n is "ssssttttaaaarrrrtttt", then the offset is relative to the beginning of the file. If it is "ccccuuuurrrrrrrreeeennnntttt", it is relative to the current access position in the file. If it is "eeeennnndddd", then it is relative to the end-of-file (a negative is before the EOF, positive is after). If _o_r_i_g_i_n is omitted, ssssttttaaaarrrrtttt is assumed. The following _o_p_t_i_o_n_s are recognized: PPPPaaaaggggeeee 11117777 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) ----rrrreeeeaaaadddd - Place a read lock on the file. Multiple processes may be accessing the file with read-locks. ----wwwwrrrriiiitttteeee - Place a write lock on the file. Only one process may be accessing a file if there is a write lock. ----nnnnoooowwwwaaaaiiiitttt - 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 ffffccccnnnnttttllll 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 ffffccccnnnnttttllll command). ffffoooorrrr____ffffiiiilllleeee _v_a_r _f_i_l_e_n_a_m_e { _c_o_d_e } This procedure implements a loop over the contents of a file. For each line in _f_i_l_e_n_a_m_e, it sets _v_a_r to the line and executes _c_o_d_e. The bbbbrrrreeeeaaaakkkk and ccccoooonnnnttttiiiinnnnuuuueeee commands work as with foreach. For example, the command ffffoooorrrr____ffffiiiilllleeee lllliiiinnnneeee ////eeeettttcccc////ppppaaaasssssssswwwwdddd {{{{eeeecccchhhhoooo $$$$lllliiiinnnneeee}}}} would echo all the lines in the password file. ffffuuuunnnnlllloooocccckkkk _f_i_l_e_I_d ?_s_t_a_r_t? ?_l_e_n_g_t_h? ?_o_r_i_g_i_n? Remove a locked from a file that was previously placed with the _f_l_o_c_k command. The arguments are the same as for the _f_l_o_c_k command, see that command for more details. ffffssssttttaaaatttt _f_i_l_e_I_d ?_i_t_e_m?|?ssssttttaaaatttt _a_r_r_a_y_v_a_r? Obtain status information about an open file. The following keys are used to identify data items: o aaaattttiiiimmmmeeee - The time of last access. o ccccttttiiiimmmmeeee - The time of last file status change o ddddeeeevvvv - The device containing a directory for the file. This value uniquely identifies the file system that contains the file. o ggggiiiidddd - The group ID of the file's group. o iiiinnnnoooo - The inode number. This field uniquely identifies the file in a given file system. o mmmmooooddddeeee - The mode of the file (see the mmmmkkkknnnnoooodddd system call). PPPPaaaaggggeeee 11118888 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) o mmmmttttiiiimmmmeeee - Time when the data in the file was last modified. o nnnnlllliiiinnnnkkkk - The number of links to the file. o ssssiiiizzzzeeee - The file size in bytes. o ttttttttyyyy - If the file is associated with a terminal, then 1 otherwise 0. o ttttyyyyppppeeee - The type of the file in symbolic form, which is one of the following values: ffffiiiilllleeee, ddddiiiirrrreeeeccccttttoooorrrryyyy, cccchhhhaaaarrrraaaacccctttteeeerrrrSSSSppppeeeecccciiiiaaaallll, bbbblllloooocccckkkkSSSSppppeeeecccciiiiaaaallll, ffffiiiiffffoooo, lllliiiinnnnkkkk, or ssssoooocccckkkkeeeetttt. o uuuuiiiidddd - The user ID of the file's owner. If one of these keys is specified as _i_t_e_m, then that data item is returned. If ssssttttaaaatttt _a_r_r_a_y_v_a_r is specified, then the information is returned in the array _a_r_r_r_a_y_v_a_r. Each of the above keys indexes an element of the array containing the data. If only _f_i_l_e_I_d 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: o rrrreeeemmmmooootttteeeehhhhoooosssstttt - If _f_i_l_e_I_d 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 returned as the this element. o llllooooccccaaaallllhhhhoooosssstttt - If _f_i_l_e_I_d 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 returned as the this element. ffffttttrrrruuuunnnnccccaaaatttteeee [----ffffiiiilllleeeeiiiidddd] _f_i_l_e _n_e_w_s_i_z_e Truncate a file to have a length of at most _n_e_w_s_i_z_e bytes. If the option ----ffffiiiilllleeeeiiiidddd is specified, _f_i_l_e is an open file identifier, otherwise it is a file path. This command is not available on all systems if the underlying operating system support is not available. The command iiiinnnnffffooooxxxx hhhhaaaavvvveeee____ttttrrrruuuunnnnccccaaaatttteeee will indicate if this command is available. On some systems, the ----ffffiiiilllleeeeiiiidddd option is not available, check the result of iiiinnnnffffooooxxxx hhhhaaaavvvveeee____ffffttttrrrruuuunnnnccccaaaatttteeee to see if it can be used. PPPPaaaaggggeeee 11119999 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) llllggggeeeettttssss _f_i_l_e_I_d ?_v_a_r_N_a_m_e? Reads the next Tcl list from the file given by _f_i_l_e_I_d and discards the terminating newline character. This command differs from the ggggeeeettttssss command, in that it reads Tcl lists rather than lines. If the list contains a newline, then that newline 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 outputing lists, as ppppuuuuttttssss will do this correctly. If _v_a_r_N_a_m_e 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 _v_a_r_N_a_m_e is set to an empty string. If _v_a_r_N_a_m_e 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 eeeeooooffff may have to be used to determine what really happened. ffffrrrreeeennnnaaaammmmeeee _o_l_d_P_a_t_h _n_e_w_P_a_t_h Renames _o_l_d_P_a_t_h to _n_e_w_P_a_t_h. This command does not support renaming across file systems. ppppiiiippppeeee ?_f_i_l_e_I_d__v_a_r__r _f_i_l_e_I_d__v_a_r__w? Create a pipe. If _f_i_l_e_I_d__v_a_r__r and _f_i_l_e_I_d__v_a_r__r are specified, then ppppiiiippppeeee will set the a variable named _f_i_l_e_I_d__v_a_r__r to contain the fileId of the side of the pipe that was opened for reading, and _f_i_l_e_I_d__v_a_r__w 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 containing the read and write fileIdw is returned as the result of the command. rrrreeeeaaaadddd____ffffiiiilllleeee ?----nnnnoooonnnneeeewwwwlllliiiinnnneeee? _f_i_l_e_N_a_m_e rrrreeeeaaaadddd____ffffiiiilllleeee _f_i_l_e_N_a_m_e _n_u_m_B_y_t_e_s This proecure reads the file _f_i_l_e_N_a_m_e and returns the contents as a string. If ----nnnnoooonnnneeeewwwwlllliiiinnnneeee is specified, then the last character 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 _n_u_m_B_y_t_e_s bytes left in the file; in this case, all the remaining bytes are returned. sssseeeelllleeeecccctttt _r_e_a_d_f_i_l_e_I_d_s ?_w_r_i_t_e_f_i_l_e_I_d_s? ?_e_x_c_e_p_t_f_i_l_e_I_d_s? ?_t_i_m_e_o_u_t? This command allows an Extended Tcl program to wait on zero or more files being ready for for reading, writing, have an exceptional condition pending, or for a timeout period to expire. _r_e_a_d_F_i_l_e_I_d_s, _w_r_i_t_e_F_i_l_e_I_d_s, _e_x_c_e_p_t_F_i_l_e_I_d_s are each lists of fileIds, as returned from ooooppppeeeennnn, to query. An empty list ({}) may be specified if a category is not used. The files specified by the _r_e_a_d_F_i_l_e_I_d_s list are checked to see if data is available for reading. The _w_r_i_t_e_F_i_l_e_I_d_s are checked if the PPPPaaaaggggeeee 22220000 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) specified files are clear for writing. The _e_x_c_e_p_t_F_i_l_e_I_d_s are checked to see if an exceptional condition has occured (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. _T_i_m_e_o_u_t 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 sssseeeelllleeeecccctttt command functions as a poll of the files, returning immediately even if none are ready. If the _t_i_m_e_o_u_t period expires with none of the files becomming 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 element will be the null list. For example: select {file3 file4 file5} {file6 file7} {} 10.5 could return {file3 file4} {file6} {} or perhaps file3 {} {} wwwwrrrriiiitttteeee____ffffiiiilllleeee _f_i_l_e_N_a_m_e _s_t_r_i_n_g ?_s_t_r_i_n_g...? This procedure writes the specified strings to the named file. TTTTCCCCPPPP////IIIIPPPP SSSSEEEERRRRVVVVEEEERRRR AAAACCCCCCCCEEEESSSSSSSS Commands are provided to access TCP/IP-based servers, and to create them. It is easy to build servers using Extended Tcl that run under iiiinnnneeeettttdddd, or even servers that run standalone and accept and manage multiple simultaneous connections. The socket file handles maybe be read using the either the ggggeeeettttssss or rrrreeeeaaaadddd command and written using either the ppppuuuuttttssss or sssseeeerrrrvvvveeeerrrr____sssseeeennnndddd command. The ffffssssttttaaaatttt rrrreeeemmmmooootttteeeehhhhoooosssstttt and ffffssssttttaaaatttt llllooooccccaaaallllhhhhoooosssstttt requests are useful both for clients and servers. To obtain the host name of the system the script is running on, use iiiidddd hhhhoooosssstttt. If a TclX script is setup to run under iiiinnnneeeettttdddd, it is launched with its stdin, stdout and stderr associated with the client socket. The standard Tcl file ids ssssttttddddiiiinnnn, ssssttttddddoooouuuutttt and ssssttttddddeeeerrrrrrrr maybe then be used to communicate with the client. PPPPaaaaggggeeee 22221111 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) sssseeeerrrrvvvveeeerrrr____ccccoooonnnnnnnneeeecccctttt ?_o_p_t_i_o_n_s? _h_o_s_t _s_e_r_v_i_c_e Open a TCP/IP connection to a server of _h_o_s_t on the port specified by _s_e_r_v_i_c_e. The server is then accessed using the standard Tcl file I/O commands. _H_o_s_t may be a host name or an IP address. _P_o_r_t may be a port number of a service name. If a destination host name is supplied and more that one address is valid for the host, the host's addresses will be tried in the order returned until one can be connected to, or the list is exhausted. You may also use the sssseeeerrrrvvvveeeerrrr____iiiinnnnffffoooo command to obtain the list of valid address. The options are: o ----bbbbuuuuffff - Specifies that the file is buffered. When writing to the file, the fffflllluuuusssshhhh command must be used to force data in the buffer to be sent to the server. Buffered access will result in significantly better performance when reading data, and will also improve the performance of a series of writes done without intervening reads. The buffering is only used when accessing the file via the ggggeeeettttssss, rrrreeeeaaaadddd, and ppppuuuuttttssss commands. The sssseeeerrrrvvvveeeerrrr____sssseeeennnndddd command does not use the buffer. o ----nnnnoooobbbbuuuuffff - The file is unbuffered. A single file id, open for both reading and writing, is returned. o ----ttttwwwwooooiiiiddddssss - Return a pair of file ids in a list. The first id is open for read access, the second for write access. The cccclllloooosssseeee command must be called against both file ids when you are done using the socket and they maybe closed independently. This option is primarily intended to implement compatibility procedures for deprecated commands, however it maybe useful for code that needs to independently manage the read and write ends of the socket. o ----mmmmyyyyiiiipppp _i_p_N_u_m_b_e_r - Define the IP number for your side of the connection. This is useful for multi-homed hosts (hosts with more than one IP address). Note that only IP addresses corresponding to network interfaces on your machine may be used. If ----mmmmyyyyiiiipppp is not specified, the operating system will assign the IP number for you. o ----mmmmyyyyppppoooorrrrtttt _p_o_r_t_N_u_m_b_e_r - Define the port number for your side of the connection. If the port number is already in use, an error will be returned. If the port number is in the privileged range, the Tcl program will have to be running as superuser, or an error will be returned. sssseeeerrrrvvvveeeerrrr____ccccrrrreeeeaaaatttteeee ?_o_p_t_i_o_n_s? Creates a TCP/IP server socket on the local machine. A file handle is returned upon successful creation. When a connection request is made to the server, the file handle becomes read-ready. Connections can be accepted using sssseeeerrrrvvvveeeerrrr____aaaacccccccceeeepppptttt. PPPPaaaaggggeeee 22222222 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) The file handle can be detected as read-ready using sssseeeelllleeeecccctttt, by using ffffccccnnnnttttllll to make the handle nonblocking and then calling sssseeeerrrrvvvveeeerrrr____aaaacccccccceeeepppptttt, or by using the TTTTkkkk ffffiiiilllleeeeeeeevvvveeeennnntttt command. Options are: o ----mmmmyyyyiiiipppp _i_p_N_u_m_b_e_r - Define the IP number for your side of the connection. This is useful for multi-homed hosts (hosts with more than one IP address). Note that only IP addresses corresponding to network interfaces on your machine may be used. If ----mmmmyyyyiiiipppp is not specified, the operating system will assign the IP number for you. o ----mmmmyyyyppppoooorrrrtttt _p_o_r_t_N_u_m_b_e_r - Define the port number for your side of the connection. If the port number is already in use, an error will be returned. If the port number is in the privileged range, the Tcl program will have to be running as superuser, or an error will be returned. o ----bbbbaaaacccckkkklllloooogggg _c_o_u_n_t - Maximum length the queue of pending connections may grow to. If a connection request arrives with the queue full, the client may receive an error with an indication of _E_C_O_N_N_R_E_F_U_S_E_D, or, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed. Note that on at least some BSD-based systems the backlog is silently limited to 5, regardless of the value specified. The default is 5. sssseeeerrrrvvvveeeerrrr____aaaacccccccceeeepppptttt ?_o_p_t_i_o_n_s? _f_i_l_e_i_d Accept a TCP/IP connection to the server socket associated with _f_i_l_e_i_d. Options are ----bbbbuuuuffff, ----nnnnoooobbbbuuuuffff and ----ttttwwwwooooiiiiddddssss. See the sssseeeerrrrvvvveeeerrrr____ccccoooonnnnnnnneeeecccctttt command for a description of these options. A file handle (or a pair of file handles when ----ttttwwwwooooiiiiddddssss) is return. sssseeeerrrrvvvveeeerrrr____iiiinnnnffffoooo aaaaddddddddrrrreeeesssssssseeeessss _h_o_s_t sssseeeerrrrvvvveeeerrrr____iiiinnnnffffoooo ooooffffffffiiiicccciiiiaaaallll____nnnnaaaammmmeeee _h_o_s_t sssseeeerrrrvvvveeeerrrr____iiiinnnnffffoooo aaaalllliiiiaaaasssseeeessss _h_o_s_t Optain information about a TCP/IP server. The argument hhhhoooosssstttt can be either a host name or an IP address. The following subcommands are recognized: o aaaaddddddddrrrreeeesssssssseeeessss - Return the list of IP addresses for _h_o_s_t. o ooooffffffffiiiicccciiiiaaaallll____nnnnaaaammmmeeee - Return official name for _h_o_s_t. o aaaalllliiiiaaaasssseeeessss - Return the list of aliases for _h_o_s_t. (Note that these are IP number aliases, not DNS _C_N_A_M_E aliases. See _i_f_c_o_n_f_i_g(_2).) sssseeeerrrrvvvveeeerrrr____sssseeeennnndddd ?_o_p_t_i_o_n_s? _f_i_l_e_i_d _s_t_r_i_n_g Send the specified string to the TCP/IP connection corresponding to _f_i_l_e_i_d. Thesssseeeerrrrvvvveeeerrrr____sssseeeennnndddd command is provide as an option to ppppuuuuttttssss for writing to a socket as it is better at detecting lost connections PPPPaaaaggggeeee 22223333 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) and other IP-related error conditions. File buffering is ignored for sssseeeerrrrvvvveeeerrrr____sssseeeennnndddd. There is no need to fffflllluuuusssshhhh after a sssseeeerrrrvvvveeeerrrr____sssseeeennnndddd. The results of mixing sssseeeerrrrvvvveeeerrrr____sssseeeennnndddd with ppppuuuuttttssss without flushing the ppppuuuuttttssss output is indeterminate. Options are: o ----nnnnoooonnnneeeewwwwlllliiiinnnneeee - Don't append a newline character to the end of the message. The default is to append a newline character. o ----ddddoooonnnnttttrrrroooouuuutttteeee - Requests that routing be bypassed and the direct interface used (usually used only by diagnostic or routing programs) o ----oooouuuuttttooooffffbbbbaaaannnndddd - Send out-of-band data on the socket. FFFFIIIILLLLEEEE SSSSCCCCAAAANNNNNNNNIIIINNNNGGGG CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS 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 _a_w_k. 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 _s_c_a_n _c_o_n_t_e_x_t. 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. ssssccccaaaannnnccccoooonnnntttteeeexxxxtttt ?_o_p_t_i_o_n? 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. Multiple scan contexts may be defined and they may be reused on multiple files. A scan context is identified by a context handle. The ssssccccaaaannnnccccoooonnnntttteeeexxxxtttt command takes the following forms: ssssccccaaaannnnccccoooonnnntttteeeexxxxtttt ccccrrrreeeeaaaatttteeee Create a new scan context. The ssssccccaaaannnnmmmmaaaattttcccchhhh 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. ssssccccaaaannnnccccoooonnnntttteeeexxxxtttt ddddeeeelllleeeetttteeee _c_o_n_t_e_x_t_h_a_n_d_l_e Delete the scan context identified by _c_o_n_t_e_x_t_h_a_n_d_l_e, and free all of the match statements and compiled regular expressions associated with the specified context. ssssccccaaaannnnccccoooonnnntttteeeexxxxtttt ccccooooppppyyyyffffiiiilllleeee _c_o_n_t_e_x_t_h_a_n_d_l_e ?_f_i_l_e_h_a_n_d_l_e? Set or return the file handle that unmatched lines are copied to. (See ssssccccaaaannnnffffiiiilllleeee). If _f_i_l_e_h_a_n_d_l_e is omitted, the copy file handle is PPPPaaaaggggeeee 22224444 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) returned. If no copy file is associated with the context, {} is returned. If a file handle is specified, it becomes the copy file for this context. If _f_i_l_e_h_a_n_d_l_e is {}, then it removes any copy file specification for the context. ssssccccaaaannnnffffiiiilllleeee ?-_c_o_p_y_f_i_l_e _c_o_p_y_F_i_l_e_I_d? _c_o_n_t_e_x_t_h_a_n_d_l_e _f_i_l_e_I_d Scan the file specified by _f_i_l_e_I_d, starting from the current file position. Check all patterns in the scan context specified by _c_o_n_t_e_x_t_h_a_n_d_l_e against it, executing the match commands corresponding to patterns matched. If the optional -_c_o_p_y_f_i_l_e argument is specified, the next argument 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 ssssccccaaaannnnccccoooonnnntttteeeexxxxtttt ccccooooppppyyyyffffiiiilllleeee command, the file is disassociated from the scan context at the end of the scan. ssssccccaaaannnnmmmmaaaattttcccchhhh ?----nnnnooooccccaaaasssseeee? _c_o_n_t_e_x_t_h_a_n_d_l_e ?_r_e_g_e_x_p? _c_o_m_m_a_n_d_s Specify Tcl _c_o_m_m_a_n_d_s, to be evaluated when _r_e_g_e_x_p is matched by a ssssccccaaaannnnffffiiiilllleeee command. The match is added to the scan context specified by _c_o_n_t_e_x_t_h_a_n_d_l_e. Any number of match statements may be specified for a give context. _R_e_g_e_x_p is a regular expression (see the rrrreeeeggggeeeexxxxpppp command). If ----nnnnooooccccaaaasssseeee is specified as the first argument, the pattern is matched regardless of alphabetic case. If _r_e_g_e_x_p 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 mmmmaaaattttcccchhhhIIIInnnnffffoooo is available to the Tcl code that is executed when an expression matches (or defaults). It contans information about the file being scanned and where within it the expression was matched. mmmmaaaattttcccchhhhIIIInnnnffffoooo is local to the top level of the match command unless declared global at that level by the Tcl gggglllloooobbbbaaaallll command. If it is to be used as a global, it _m_u_s_t be declared global before ssssccccaaaannnnffffiiiilllleeee is called (since ssssccccaaaannnnffffiiiilllleeee sets the mmmmaaaattttcccchhhhIIIInnnnffffoooo before the match code is executed, a subsequent gggglllloooobbbbaaaallll will override the local variable). The following array entries are available: mmmmaaaattttcccchhhhIIIInnnnffffoooo((((lllliiiinnnneeee)))) Contains the text of the line of the file that was matched. mmmmaaaattttcccchhhhIIIInnnnffffoooo((((ooooffffffffsssseeeetttt)))) The byte offset into the file of the first character of the line that was matched. PPPPaaaaggggeeee 22225555 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) mmmmaaaattttcccchhhhIIIInnnnffffoooo((((lllliiiinnnneeeennnnuuuummmm)))) 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. mmmmaaaattttcccchhhhIIIInnnnffffoooo((((ccccoooonnnntttteeeexxxxtttt)))) The context handle of the context that this scan is associated with. mmmmaaaattttcccchhhhIIIInnnnffffoooo((((hhhhaaaannnnddddlllleeee)))) The file id (handle) of the file currently being scanned. mmmmaaaattttcccchhhhIIIInnnnffffoooo((((ccccooooppppyyyyHHHHaaaannnnddddlllleeee)))) The file id (handle) of the file specified by the ----ccccooooppppyyyyffffiiiilllleeee option. The element does not exist if ----ccccooooppppyyyyffffiiiilllleeee was not specified. mmmmaaaattttcccchhhhIIIInnnnffffoooo((((ssssuuuubbbbmmmmaaaattttcccchhhh0000)))) Will contain the characters matching the first parenthesized subexpression. The second will be contained in ssssuuuubbbbmmmmaaaattttcccchhhh1111, etc. mmmmaaaattttcccchhhhIIIInnnnffffoooo((((ssssuuuubbbbiiiinnnnddddeeeexxxx0000)))) 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 ssssuuuubbbbiiiinnnnddddeeeexxxx1111, etc. All ssssccccaaaannnnmmmmaaaattttcccchhhh 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 ssssccccaaaannnnmmmmaaaattttcccchhhh pattern-command pairs may be skipped for a file line if a ccccoooonnnnttttiiiinnnnuuuueeee is executed by the Tcl code of a preceding, matched pattern. If a rrrreeeettttuuuurrrrnnnn is executed in the body of the match command, the ssssccccaaaannnnffffiiiilllleeee command currently in progress returns, with the value passed to rrrreeeettttuuuurrrrnnnn as its return value. MMMMAAAATTTTHHHH CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS Several extended math commands commands make many additional math functions available in TclX. In addition, a set of procedures provide command access to the math functions supported by the eeeexxxxpppprrrr command. The following procedures provide command interfaces to the expr math functions. They take the same arguments as the eeeexxxxpppprrrr functions and may take expressions as arguments. aaaabbbbssss aaaaccccoooossss aaaassssiiiinnnn aaaattttaaaannnn2222 aaaattttaaaannnn cccceeeeiiiillll ccccoooossss ccccoooosssshhhh ddddoooouuuubbbblllleeee eeeexxxxpppp fffflllloooooooorrrr ffffmmmmoooodddd hhhhyyyyppppooootttt iiiinnnntttt lllloooogggg11110000 lllloooogggg ppppoooowwww rrrroooouuuunnnndddd ssssiiiinnnn ssssiiiinnnnhhhh PPPPaaaaggggeeee 22226666 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) ssssqqqqrrrrtttt ttttaaaannnn ttttaaaannnnhhhh mmmmaaaaxxxx _n_u_m_1 _n_u_m_2 ?.._n_u_m_N? eeeexxxxpppprrrr mmmmaaaaxxxx((((nnnnuuuummmm1111,,,, nnnnuuuummmm2222)))) 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 mmmmaaaaxxxx in the Tcl eeeexxxxpppprrrr command. mmmmiiiinnnn _n_u_m_1 _n_u_m_2 ?.._n_u_m_N? eeeexxxxpppprrrr mmmmiiiinnnn((((nnnnuuuummmm1111,,,, nnnnuuuummmm2222)))) 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 mmmmiiiinnnn in the Tcl eeeexxxxpppprrrr command. rrrraaaannnnddddoooommmm _l_i_m_i_t | sssseeeeeeeedddd ?_s_e_e_d_v_a_l? Generate a pseudorandom integer number greater than or equal to zero and less than _l_i_m_i_t. If sssseeeeeeeedddd is specified, then the command resets the random number generator to a starting point derived from the sssseeeeeeeeddddvvvvaaaallll. This allows one to reproduce pseudorandom number sequences for testing purposes. If _s_e_e_d_v_a_l 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. LLLLIIIISSSSTTTT MMMMAAAANNNNIIIINNNNIIIIPPPPUUUULLLLAAAATTTTIIIIOOOONNNN CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS Extended Tcl provides additional list manipulation commands and procedures. iiiinnnntttteeeerrrrsssseeeecccctttt _l_i_s_t_a _l_i_s_t_b Procedure to return the logical intersection of two lists. The returned list will be sorted. iiiinnnntttteeeerrrrsssseeeecccctttt3333 _l_i_s_t_a _l_i_s_t_b Procedure to intersects two lists, returning a list containing three lists: The first list returned is everything in _l_i_s_t_a that wasn't in _l_i_s_t_b. The second list contains the intersection of the two lists, and the third list contains all the elements that were in _l_i_s_t_b but weren't in _l_i_s_t_a. The returned lists will be sorted. llllaaaassssssssiiiiggggnnnn _l_i_s_t _v_a_r ?_v_a_r...? Assign successive elements of a list to specified variables. If there are more variable names than fields, the remaining variables are set to the empty string. If there are more elements than variables, a list of the unassigned elements is returned. For example, PPPPaaaaggggeeee 22227777 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) lassign {dave 100 200 {Dave Foo}} name uid gid longName Assigns _n_a_m_e to ``dave'', _u_i_d to ``100'', _g_i_d to ``200'', and _l_o_n_g_N_a_m_e to ``Dave Foo''. lllleeeemmmmppppttttyyyy _l_i_s_t Determine if the specified list is empty. If empty, 1 is returned, otherwise, 0 is returned. This command is an alternative to comparing a list to an empty string. llllmmmmaaaattttcccchhhh ?_m_o_d_e? _l_i_s_t _p_a_t_t_e_r_n Search the elements of _l_i_s_t, returning a list of all elements matching _p_a_t_t_e_r_n. If none match, an empty list is returned. The _m_o_d_e argument indicates how the elements of the list are to be matched against _p_a_t_t_e_r_n and it must have one of the following values: ----eeeexxxxaaaacccctttt The list element must contain exactly the same string as _p_a_t_t_e_r_n. ----gggglllloooobbbb _P_a_t_t_e_r_n is a glob-style pattern which is matched against each list element using the same rules as the ssssttttrrrriiiinnnngggg mmmmaaaattttcccchhhh command. ----rrrreeeeggggeeeexxxxpppp _P_a_t_t_e_r_n is treated as a regular expression and matched against each list element using the same rules as the rrrreeeeggggeeeexxxxpppp command. If _m_o_d_e is omitted then it defaults to ----gggglllloooobbbb. llllrrrrmmmmdddduuuuppppssss _l_i_s_t Procedure to remove duplicate elements from a list. The returned list will be sorted. llllvvvvaaaarrrrccccaaaatttt _v_a_r _s_t_r_i_n_g ?_s_t_r_i_n_g...? This command treats each _s_t_r_i_n_g argument as a list and concatenates them to the end of the contents of _v_a_r, forming a a single list. The list is stored back into _v_a_r and also returned as the result. if _v_a_r does not exist, it is created. llllvvvvaaaarrrrppppoooopppp _v_a_r ?_i_n_d_e_x_E_x_p_r? ?_s_t_r_i_n_g? The llllvvvvaaaarrrrppppoooopppp command pops (deletes) the element indexed by the expression _i_n_d_e_x_E_x_p_r from the list contained in the variable _v_a_r. If _i_n_d_e_x is omitted, then 0 is assumed. If _s_t_r_i_n_g, is specified, then the deleted element is replaced by _s_t_r_i_n_g. 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 _i_n_d_e_x_E_x_p_r starts with the string eeeennnndddd, then eeeennnndddd is replaced with the index of the last element in the list. If the expression starts with lllleeeennnn, then lllleeeennnn is replaced with the length of PPPPaaaaggggeeee 22228888 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) the list. llllvvvvaaaarrrrppppuuuusssshhhh _v_a_r _s_t_r_i_n_g ?_i_n_d_e_x_E_x_p_r? The llllvvvvaaaarrrrppppuuuusssshhhh command pushes (inserts) _s_t_r_i_n_g as an element in the list contained in the variable _v_a_r. The element is inserted before position _i_n_d_e_x_E_x_p_r in the list. If _i_n_d_e_x is omitted, then 0 is assumed. If _v_a_r does not exists, it is created. If the expression _i_n_d_e_x_E_x_p_r starts with the string eeeennnndddd, then eeeennnndddd is replaced with the index of the last element in the list. If the expression starts with lllleeeennnn, then lllleeeennnn is replaced with the length of the list. Note the a value of eeeennnndddd means insert the string before the last element. uuuunnnniiiioooonnnn _l_i_s_t_a _l_i_s_t_b Procedure to return the logical union of the two specified lists. Any duplicate elements are removed. KKKKEEEEYYYYEEEEDDDD LLLLIIIISSSSTTTTSSSS Extended Tcl defines a special type of list referred to as _k_e_y_e_d _l_i_s_t_s. These lists provided a structured data type built upon standard Tcl lists. This provides a functionality similar to _s_t_r_u_c_ts in the C programming 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 refered to as _f_i_e_l_d_s. This is an example of a keyed list: {{NAME {Frank Zappa}} {JOB {musician and composer}}} If the variable ppppeeeerrrrssssoooonnnn contained the above list, then kkkkeeeeyyyyllllggggeeeetttt ppppeeeerrrrssssoooonnnn NNNNAAAAMMMMEEEE would return {{{{FFFFrrrraaaannnnkkkk ZZZZaaaappppppppaaaa}}}}. Executing the command: kkkkeeeeyyyyllllsssseeeetttt ppppeeeerrrrssssoooonnnn IIIIDDDD 111100006666 would make ppppeeeerrrrssssoooonnnn contain {{ID 106} {NAME {Frank Zappa}} {JOB {musician and composer}} Fields may contain subfields; `.' is the seperator character. Subfields are actually fields where the value is another keyed list. Thus the following list has the top level fields _I_D and _N_A_M_E, and subfields _N_A_M_E._F_I_R_S_T and _N_A_M_E._L_A_S_T: {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}} There is no limit to the recursive depth of subfields, allowing one to build complex data structures. PPPPaaaaggggeeee 22229999 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) 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. kkkkeeeeyyyyllllddddeeeellll _l_i_s_t_v_a_r _k_e_y Delete the field specified by _k_e_y from the keyed list in the variable _l_i_s_t_v_a_r. This removes both the key and the value from the keyed list. kkkkeeeeyyyyllllggggeeeetttt _l_i_s_t_v_a_r ?_k_e_y? ?_r_e_t_v_a_r | {}? Return the value associated with _k_e_y from the keyed list in the variable _l_i_s_t_v_a_r. If _r_e_t_v_a_r is not specified, then the value will be returned as the result of the command. In this case, if _k_e_y is not found in the list, an error will result. If _r_e_t_v_a_r is specified and _k_e_y is in the list, then the value is returned in the variable _r_e_t_v_a_r and the command returns 1111 if the key was present within the list. If _k_e_y isn't in the list, the command will return 0000, and _r_e_t_v_a_r will be left unchanged. If {{{{}}}} is specified for _r_e_t_v_a_r, 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 _k_e_y is omitted, then a list of all the keys in the keyed list is returned. kkkkeeeeyyyyllllkkkkeeeeyyyyssss _l_i_s_t_v_a_r ?_k_e_y? Return the a list of the keyes in the keyed list in the variable _l_i_s_t_v_a_r. If _k_e_y_s is specified, then it is the name of a key field who's subfield keys are to be retrieve. kkkkeeeeyyyyllllsssseeeetttt _l_i_s_t_v_a_r _k_e_y _v_a_l_u_e ?_k_e_y_2 _v_a_l_u_e_2 ...? Set the value associated with _k_e_y, in the keyed list contained in the variable _l_i_s_t_v_a_r, to _v_a_l_u_e. If listvar does not exists, it is created. If _k_e_y is not currently in the list, it will be added. If it already exists, _v_a_l_u_e replaces the existing value. Multiple keywords and values may be specified, if desired. SSSSTTTTRRRRIIIINNNNGGGG AAAANNNNDDDD CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR MMMMAAAANNNNIIIIPPPPUUUULLLLAAAATTTTIIIIOOOONNNN CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS 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 _t_r program). ccccccccoooollllllllaaaatttteeee ????----llllooooccccaaaallll???? _s_t_r_i_n_g_1 _s_t_r_i_n_g_2 This command compares two strings. If returns ----1111 if _s_t_r_i_n_g_1 is less than _s_t_r_i_n_g_2, 0000 if they are equal amd 1111 if _s_t_r_i_n_g_1 is greater than _s_t_r_i_n_g_2. If ----llllooooccccaaaallll is specified, the strings are compared according to the PPPPaaaaggggeeee 33330000 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) collation environment of the current locale. cccceeeeqqqquuuuaaaallll _s_t_r_i_n_g_1 _s_t_r_i_n_g_2 This command compares two strings for equality. It returns 1111 if _s_t_r_i_n_g_1 and _s_t_r_i_n_g_2 are the identical and 0000 if they are not. This command is a short-cut for ssssttttrrrriiiinnnngggg ccccoooommmmppppaaaarrrreeee and avoids the problems with string expressions being treated unintentionally as numbers. cccciiiinnnnddddeeeexxxx _s_t_r_i_n_g _i_n_d_e_x_E_x_p_r Returns the character indexed by the expression _i_n_d_e_x_E_x_p_r (zero based) from _s_t_r_i_n_g. If the expression _i_n_d_e_x_E_x_p_r starts with the string eeeennnndddd, then eeeennnndddd is replaced with the index of the last character in the string. If the expression starts with lllleeeennnn, then lllleeeennnn is replaced with the length of the string. cccclllleeeennnnggggtttthhhh _s_t_r_i_n_g Returns the length of _s_t_r_i_n_g in characters. This command is a shortcut for: ssssttttrrrriiiinnnngggg lllleeeennnnggggtttthhhh _s_t_r_i_n_g ccccrrrraaaannnnggggeeee _s_t_r_i_n_g _f_i_r_s_t_E_x_p_r _l_a_s_t_E_x_p_r Returns a range of characters from _s_t_r_i_n_g starting at the character indexed by the expression _f_i_r_s_t_E_x_p_r (zero-based) until the character indexed by the expression _l_a_s_t_E_x_p_r. If the expression _f_i_r_s_t_E_x_p_r or llllaaaassssttttEEEExxxxpppprrrr starts with the string eeeennnndddd, then eeeennnndddd is replaced with the index of the last character in the string. If the expression starts with lllleeeennnn, then lllleeeennnn is replaced with the length of the string. ccccssssuuuubbbbssssttttrrrr _s_t_r_i_n_g _f_i_r_s_t_E_x_p_r _l_e_n_g_t_h_E_x_p_r Returns a range of characters from _s_t_r_i_n_g starting at the character indexed by the expression _f_i_r_s_t_E_x_p_r (zero-based) for _l_e_n_g_t_h_E_x_p_r characters. If the expression _f_i_r_s_t_E_x_p_r or lllleeeennnnggggtttthhhhEEEExxxxpppprrrr starts with the string eeeennnndddd, then eeeennnndddd is replaced with the index of the last character in the string. If the expression starts with lllleeeennnn, then lllleeeennnn is replaced with the length of the string. ccccttttooookkkkeeeennnn _s_t_r_v_a_r _s_e_p_a_r_a_t_o_r_s Parse a token out of a character string. The string to parse is contained in the variable named _s_t_r_v_a_r. The string _s_e_p_a_r_a_t_o_r_s 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 _s_t_r_v_a_r will be modified to contain the remainder of the string following the token. PPPPaaaaggggeeee 33331111 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) cccceeeexxxxppppaaaannnndddd _s_t_r_i_n_g Expand backslash sequences in _s_t_r_i_n_g to their actual characters. No other substitution takes place. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _c_l_a_s_s _s_t_r_i_n_g ccccttttyyyyppppeeee determines whether all characters in _s_t_r_i_n_g are of the specified _c_l_a_s_s. It returns 1111 if they are all of _c_l_a_s_s, and 0000 if they are not, or if the string is empty. This command also provides another method (besides ffffoooorrrrmmmmaaaatttt and ssssccccaaaannnn) of converting between an ASCII character and its numeric value. The following ccccttttyyyyppppeeee commands are available: ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _a_l_n_u_m _s_t_r_i_n_g Tests that all characters are alphabetic or numeric characters as defined by the character set. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _a_l_p_h_a _s_t_r_i_n_g Tests that all characters are alphabetic characters as defined by the character set. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _a_s_c_i_i _s_t_r_i_n_g Tests that all characters are an ASCII character (a non- negative number less than 0200). ccccttttyyyyppppeeee cccchhhhaaaarrrr _n_u_m_b_e_r Converts the numeric value, _s_t_r_i_n_g, to an ASCII character. Number must be in the range 0 through 255. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _c_n_t_r_l _s_t_r_i_n_g Tests that all characters are ``control characters'' as defined by the character set. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _d_i_g_i_t _s_t_r_i_n_g Tests that all characters are valid decimal digits, i.e. 0 through 9. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _g_r_a_p_h _s_t_r_i_n_g Tests that all characters within are any character for which _c_t_y_p_e _p_r_i_n_t is true, except for space characters. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _l_o_w_e_r _s_t_r_i_n_g Tests that all characters are lowercase letters as defined by the character set. ccccttttyyyyppppeeee oooorrrrdddd _c_h_a_r_a_c_t_e_r Convert a character into its decimal numeric value. The first character of the string is converted. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _s_p_a_c_e _s_t_r_i_n_g Tests that all characters are either a space, horizontal-tab, carriage return, newline, vertical-tab, or form-feed. PPPPaaaaggggeeee 33332222 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _p_r_i_n_t _s_t_r_i_n_g Tests that all characters are a space or any character for which _c_t_y_p_e _a_l_n_u_m or _c_t_y_p_e _p_u_n_c_t is true or other ``printing character'' as defined by the character set. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _p_u_n_c_t _s_t_r_i_n_g Tests that all characters are made up of any of the characters other than the ones for which aaaallllnnnnuuuummmm, ccccnnnnttttrrrrllll, or ssssppppaaaacccceeee is true. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _u_p_p_e_r _s_t_r_i_n_g Tests that all characters are uppercase letters as defined by the character set. ccccttttyyyyppppeeee ?-_f_a_i_l_i_n_d_e_x _v_a_r? _x_d_i_g_i_t _s_t_r_i_n_g Tests that all characters are valid hexadecimal digits, that is _0 through _9, a through _f or _A through _F. If -_f_a_i_l_i_n_d_e_x is specified, then the index into _s_t_r_i_n_g of the first character that did not match the class is returned in _v_a_r. rrrreeeepppplllliiiiccccaaaatttteeee _s_t_r_i_n_g _c_o_u_n_t_E_x_p_r Returns _s_t_r_i_n_g, replicated the number of times indicated by the expression _c_o_u_n_t_E_x_p_r. ttttrrrraaaannnnsssslllliiiitttt _i_n_r_a_n_g_e _o_u_t_r_a_n_g_e _s_t_r_i_n_g Translate characters in _s_t_r_i_n_g, changing characters occuring in _i_n_r_a_n_g_e to the corresponding character in _o_u_t_r_a_n_g_e. _I_n_r_a_n_g_e and _o_u_t_r_a_n_g_e may be list of characters or a range in the form `A-M'. For example: translit a-z A-Z foobar returns "FOOBAR". XXXXPPPPGGGG////3333 MMMMEEEESSSSSSSSAAAAGGGGEEEE CCCCAAAATTTTAAAALLLLOOOOGGGG CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS 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 languages, and they can altered, and new languages added, without affecting any Tcl or C source code, greatly easing the maintenance difficulties 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 message 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 PPPPaaaaggggeeee 33333333 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) on ccccaaaattttooooppppeeeennnn, in which case ccccaaaattttggggeeeettttssss 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 normally 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 ccccaaaattttggggeeeettttssss 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 multiple Tcl interpreters within the same process may pass and share message catalog handles. ccccaaaattttooooppppeeeennnn ?----ffffaaaaiiiillll|----nnnnooooffffaaaaiiiillll? _c_a_t_n_a_m_e Open the message catalog _c_a_t_n_a_m_e. This may be a relative path name, in which case the NNNNLLLLSSSSPPPPAAAATTTTHHHH environment variable is searched to find an absolute path to the message catalog. A handle in the form mmmmssssggggccccaaaatttt_N is returned. Normally, errors are ignored, and in the case of a failed call to ccccaaaattttooooppppeeeennnn, a handle is returned to an unopened message catalog. (This handle may still be passed to ccccaaaattttggggeeeettttssss and ccccaaaattttcccclllloooosssseeee, causing ccccaaaattttggggeeeettttssss to simply return the default string, as described above. If the ----ffffaaaaiiiillll option is specified, an error is returned if the open fails. The option ----nnnnooooffffaaaaiiiillll specifies the default behavior of not returning an error when ccccaaaattttooooppppeeeennnn fails to open a specified message catalog. If the handle from a failed ccccaaaattttooooppppeeeennnn is passed to ccccaaaattttggggeeeettttssss, the default string is returned. ccccaaaattttggggeeeettttssss _c_a_t_H_a_n_d_l_e _s_e_t_n_u_m _m_s_g_n_u_m _d_e_f_a_u_l_t_s_t_r Retrieve a message form a message catalog. _C_a_t_H_a_n_d_l_e should be a Tcl message catalog handle that was returned by ccccaaaattttooooppppeeeennnn. _S_e_t_n_u_m is the message set number, and _m_s_g_n_u_m is the message number. If the message catalog was not opened, or the message set or message number cannot be found, then the default string, _d_e_f_a_u_l_t_s_t_r, is returned. ccccaaaattttcccclllloooosssseeee ?----ffffaaaaiiiillll|----nnnnooooffffaaaaiiiillll? _c_a_t_h_a_n_d_l_e Close the message catalog specified by _c_a_t_h_a_n_d_l_e. Normally, errors are ignored. If ----ffffaaaaiiiillll is specified, any errors closing the message catalog file are returned. The option ----nnnnooooffffaaaaiiiillll specifies the default behavior of not returning an error. The use of ----ffffaaaaiiiillll only makes sense if it was also specified in the call to ccccaaaattttooooppppeeeennnn. EEEEXXXXTTTTEEEENNNNDDDDEEEEDDDD TTTTCCCCLLLL SSSSHHHHEEEELLLLLLLL ttttccccllll ????----qqqqnnnn???? ????----ffff???? ????_s_c_r_i_p_t????||||????----cccc _c_o_m_m_a_n_d???? ????_a_r_g_s? TTTTccccllll starts the interactive Tcl command interpreter. The Tcl shell provides an environment for writing, debugging and executing Tcl scripts. The functionality of the Tcl shell can be easily obtained by any application that includes Tcl. PPPPaaaaggggeeee 33334444 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) The ttttccccllll command, issued without any arguments, invokes an interactive Tcl shell, allowing the user to interact directly with Tcl, executing any Tcl commands at will and viewing their results. If _s_c_r_i_p_t is specified, then the script is executed non-interactively with any additional arguments, _a_r_g_s, being supplied in the global Tcl variable `aaaarrrrggggvvvv'. If _c_o_m_m_a_n_d is supplied, then this command (or semicolon-separated series of commands) is executed, with `aaaarrrrggggvvvv' containing any _a_r_g_s. The Tcl shell is intended as an environment for Tcl program development and execution. While it is not a full-featured interactive shell, it provides a comfortable environment for the interactive development of Tcl code. Note that the package library code described here overrides the uuuunnnnkkkknnnnoooowwwwnnnn command provided as part of the standard Berkeley Tcl library facility, although Tcl source libraries coded to that standard can be loaded and used by Extended Tcl. The following command line flags are recognized by the Tcl shell command line parser: ----qqqq Quick initialization flag. The Tcl initiaization file is not evaluated and the aaaauuuuttttoooo____ppppaaaatttthhhh variable is not set. Tcl auto-load libraries will not be available. ----nnnn No procedure call stack dump. The procedure call stack will not be displayed when an error occurs, only the error message. Useful in the #! line of already debugged scripts. ----ffff Takes the next argument as a script for Tcl to source, rather than entering interactive mode. The ----ffff flag is optional. Normally the first argument that does not start with a `-' is taken as the script to execute unless the `-c' option is specified. Any following arguments are passed to the script via aaaarrrrggggvvvv, thus any other Tcl shell command-line flags must precede this option. ----cccc Take the next argument as a Tcl command to execute. It may contain series of commands to execute, separated by `;'. Any following arguments are passed in aaaarrrrggggvvvv, thus, as with ----ffff, any other Tcl shell flags must precede this option. -------- Mark the end of the arguments to the Tcl shell. All arguments following this are passed in the Tcl variable aaaarrrrggggvvvv. This is useful to pass arguments without attempting to execute a Tcl script. The result string returned by a command executed from the Tcl shell command line is normally echoed back to the user. If an error occurs, then the string result is displayed, along with the error message. The error message will be preceded by the string ``Error:''. PPPPaaaaggggeeee 33335555 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) The sssseeeetttt command is a special case. If the command is called to set a variable (i.e. with two arguments), then the result will not be echoed. If only one argument, the name of a variable, is supplied to sssseeeetttt, then the result will be echoed. If an unknown Tcl command is entered from the command line, then the Unix command path, specified in the environment variable PPPPAAAATTTTHHHH, will be searched for a command of the same name. If the command is found, it will be executed with any arguments remaining on the Tcl command line being passed as arguments to the command. This feature is provided to enhance the interactive environment for developing Tcl scripts. Automatic execution of programs in this manner is only supported from the command line, not in script files or in procedures, to reduce confusion and mistakes while programming in Tcl. Scripts should use the Tcl eeeexxxxeeeecccc or ssssyyyysssstttteeeemmmm commands to run Unix commands. The following variables are set and/or used by the Tcl shell. aaaarrrrggggvvvv0000 Contains the name of the Tcl program specified on the command line or the name that the Tcl shell was invoked under if no program was specified. aaaarrrrggggcccc Contains a count of the number of _a_r_g_v arguments (0 if none). aaaarrrrggggvvvv A list containing the arguments passed in from the command line, excluding arguments used by the Tcl shell. The first element is the first passed argument, not the program name. ttttccccllll____iiiinnnntttteeeerrrraaaaccccttttiiiivvvveeee Set to 1111 if Tcl shell is invoked interactively, or 0000 if the Tcl shell is directly executing a script. Normally checked by scripts so that they can function as a standalone application if specified on the command line, but merely load in and not execute if loaded during an interactive invocation of Tcl. aaaauuuuttttoooo____ppppaaaatttthhhh Path to search to locate Tcl scripts. Used by the aaaauuuuttttoooo____llllooooaaaadddd command and the TclX unknown command handler. The path is a Tcl list of directory names. ttttccccllllxxxx____lllliiiibbbbrrrraaaarrrryyyy Path to the TclX runtime library. If your running the TclX shell or an appilcation based on it (like wishx), this is the same value returned by "info library". ttttccccllll____pppprrrroooommmmpppptttt1111 Contains code to run to output the prompt used when interactively prompting for commands. ttttccccllll____pppprrrroooommmmpppptttt2222 Contains code to run to output the prompt used when interactively prompting for continuation of an incomplete command. PPPPaaaaggggeeee 33336666 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) ttttccccllllxxxx____eeeerrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr If this variable is set to the name of a procedure, that procedure will be call if an uncaught error occurs. The procedure will be passed a single argument of the error message, however to allow future expansion, the procedure should have a final argument of aaaarrrrggggssss. The procedure is only called in non-interactive shells. If the procedure returns normally, the program will just exit without any error being issued by the shell. Generally the procedure should exit with a non-zero exit code once the error has been processed. It is not possible to continue executing the code in which the error occurred. This is useful for logging eeeerrrrrrrroooorrrrIIIInnnnffffoooo or e-mailing it to the maintainer. TTTTCCCCLLLLXXXXEEEENNNNVVVV Array that contains information used internally by various Tcl procedures that are part of the TclX shell. Don't change this array unless you know what your doing. When Extended Tcl is installed, the standard runtime files are places in the Tcl master directory, which is configured when Tcl is built. This master directory normally contains the Tcl initialization file (TclInit.tcl), the standard Tcl library file (tcl.tlib) and the help files. The Tcl master directory is named after the version of Tcl it is associated with, e.g. ////uuuussssrrrr////llllooooccccaaaallll////ttttccccllllXXXX////7777....4444aaaa. The path to the Tcl master directory is available from the iiiinnnnffffoooo lllliiiibbbbrrrraaaarrrryyyy command. The location of the Tcl master directory can be overridden with the TTTTCCCCLLLL____LLLLIIIIBBBBRRRRAAAARRRRYYYY environment variable. The first step in initializing the Tcl shell is to locate the Tcl initialization file, normally TTTTccccllllIIIInnnniiiitttt....ttttccccllll. If an environment variable TTTTCCCCLLLLIIIINNNNIIIITTTT exists, it contains the path to the Tcl initialization file. If the TTTTCCCCLLLLIIIINNNNIIIITTTT environment variable is not set, the file TTTTccccllllIIIInnnniiiitttt....ttttccccllll is used from the default Tcl master directory. TTTTccccllll then evaulates the Tcl initialization file. The aaaauuuuttttoooo____ppppaaaatttthhhh variable is initialized to the Tcl master directory and may be augmented by the intialization file or the application. Other procedures and variables used by the Extended Tcl shell are also defined by this file. If the Tcl is invoked interactively, it will source a file named ._t_c_l_r_c in the user's home directory, if it exists. Tcl is viewed primarily as a programming language, not an interactive shell, so the ._t_c_l_r_c is intended for use for loading development utilities, not to support applications, which should not have to rely on the user's environment in such a manner. The Extended Tcl Tk shell, wwwwiiiisssshhhhxxxx, has an additional master directory and initialization file. It use the environment variable TTTTKKKK____LLLLIIIIBBBBRRRRAAAARRRRYYYY to override the default location of the Tk master directory. PPPPaaaaggggeeee 33337777 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) HELP FACILITY 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 subjects and help pages. Help files are found by searching directories named hhhheeeellllpppp in the directories listed in the aaaauuuuttttoooo____ppppaaaatttthhhh 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 _a_d_d_p_a_t_h_s are additional paths to search for help directories. By default, only the _a_u_t_o__p_a_t_h used by ttttccccllllhhhheeeellllpppp 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: hhhheeeellllpppp Help, without arguments, lists of all the help subjects and pages under the current help subject. hhhheeeellllpppp _s_u_b_j_e_c_t Displays all of help pages and lower level subjects (if any exist) under the subject _s_u_b_j_e_c_t. hhhheeeellllpppp _s_u_b_j_e_c_t/_h_e_l_p_p_a_g_e Display the specified help page. The help output is passed through a simple pager if output exceeds 23 lines, pausing waiting for a return to be entered. If any other character is entered, the output is terminated. hhhheeeellllppppccccdddd ????_s_u_b_j_e_c_t? Change the current subject, which is much like the Unix current directory. If _s_u_b_j_e_c_t is not specified, return to the top-level of the help tree. Help subject path names may also include ``..'' elements. hhhheeeellllppppppppwwwwdddd Displays the current help subject. hhhheeeellllpppp hhhheeeellllpppp |||| ???? Displays help on the help facility at any directory level. PPPPaaaaggggeeee 33338888 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) aaaapppprrrrooooppppoooossss _p_a_t_t_e_r_n 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 rrrreeeeggggeeeexxxxpppp command). TTTTCCCCLLLL LLLLOOOOAAAADDDDAAAABBBBLLLLEEEE LLLLIIIIBBBBRRRRAAAARRRRIIIIEEEESSSS AAAANNNNDDDD PPPPAAAACCCCKKKKAAAAGGGGEEEESSSS Extended Tcl supports standard Tcl ttttccccllllIIIInnnnddddeeeexxxx 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 ....ttttlllliiiibbbb. An index file with the suffix ....ttttnnnnddddxxxx, corresponding to the package library. The ....ttttnnnnddddxxxx will be automatically created by Tcl whenever it is out of date or missing (provided there is write access to the directory. The variable aaaauuuuttttoooo____ppppaaaatttthhhh 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 aaaauuuuttttoooo____ppppaaaatttthhhh variable is changed during execution of a program, it will be re- searched. Only the first package of a given name found during the execution of a program is loaded. This can be overridden with llllooooaaaaddddlllliiiibbbbiiiinnnnddddeeeexxxx command. The start of a package is delimited by: ####@@@@ppppaaaacccckkkkaaaaggggeeee:::: _p_a_c_k_a_g_e__n_a_m_e _p_r_o_c_1 ?.._p_r_o_c_N? These lines must start in column one. Everything between the ####@@@@ppppaaaacccckkkkaaaaggggeeee:::: keyword and the next ####@@@@ppppaaaacccckkkkaaaaggggeeee:::: keyword or a ####@@@@ppppaaaacccckkkkeeeennnndddd keyword, or the end of the file, becomes part of the named package. The specified procedures, _p_r_o_c_1.._p_r_o_c_N, 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 ####@@@@ppppaaaacccckkkkeeeennnndddd 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 _p_a_c_k_a_g_e__n_a_m_e, 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. PPPPaaaaggggeeee 33339999 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) For example, in a package source file, the presence of the following line: ####@@@@ppppaaaacccckkkkaaaaggggeeee:::: ddddiiiirrrreeeeccccttttoooorrrryyyy____ssssttttaaaacccckkkk ppppuuuusssshhhhdddd ppppooooppppdddd ddddiiiirrrrssss says that the text lines following that line in the package file up to the next _p_a_c_k_a_g_e line or the end of the file is a package named ddddiiiirrrreeeeccccttttoooorrrryyyy____ssssttttaaaacccckkkk and that an attempt to execute either _p_u_s_h_d, _p_o_p_d or _d_i_r_s when the routine is not already defined will cause the ddddiiiirrrreeeeccccttttoooorrrryyyy____ssssttttaaaacccckkkk portion of the package file to be loaded. PPPPAAAACCCCKKKKAAAAGGGGEEEE LLLLIIIIBBBBRRRRAAAARRRRYYYY MMMMAAAANNNNAAAAGGGGEEEEMMMMEEEENNNNTTTT CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS 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 management commands and variables are also supported. aaaauuuuttttoooo____ccccoooommmmmmmmaaaannnnddddssss ?----llllooooaaaaddddeeeerrrrssss? Lists the names of all known loadable procedures and commands procedures. If ----llllooooaaaaddddeeeerrrrssss is specified, the command that will be executed to load the command will also be returned. bbbbuuuuiiiillllddddppppaaaacccckkkkaaaaggggeeeeiiiinnnnddddeeeexxxx _l_i_b_f_i_l_e_l_i_s_t Build index files for package libraries. The argument _l_i_b_f_i_l_e_l_i_s_t is a list of package libraries. Each name must end with the suffix ....ttttlllliiiibbbb. A corresponding ....ttttnnnnddddxxxx file will be built. The user must have write access to the directory containing each library. ccccoooonnnnvvvveeeerrrrtttt____lllliiiibbbb _t_c_l_I_n_d_e_x _p_a_c_k_a_g_e_l_i_b ?_i_g_n_o_r_e? Convert a Ousterhout style _t_c_l_I_n_d_e_x index file and associate source files into a package library ppppaaaacccckkkkaaaaggggeeeelllliiiibbbb. If ppppaaaacccckkkkaaaaggggeeeelllliiiibbbb does not have a ....ttttlllliiiibbbb extension, one will be added. Any files specified in _t_c_l_I_n_d_e_x that are in the list _i_g_n_o_r_e will be skipped. Files listed in _i_g_n_o_r_e should just be the base file names, not full paths. aaaauuuuttttoooo____llllooooaaaadddd ?_c_o_m_m_a_n_d? Attempt to load the specified _c_o_m_m_a_n_d from a loadable library. loading the package containing the procedure. If the package indexes have not been loaded for all package libraries in aaaauuuuttttoooo____ppppaaaatttthhhh, they will be loaded. Out-of-date library indexes will be rebuilt if they are writable. The procedure returns 1111 if the command was sucessfully loaded, or 0000 if it was not. Duplicated package names are skipped, the first package of a given name found in the path is loaded. If the aaaauuuuttttoooo____ppppaaaatttthhhh has changed since the last load, indexes will be reloaded (duplicate packages will not be redefined). If _c_o_m_m_a_n_d is not specified, the indexes will be loaded, if they have not alreay been loaded or if the aaaauuuuttttoooo____ppppaaaatttthhhh variable has changed, but no command will be loaded. PPPPaaaaggggeeee 44440000 TTTTccccllllXXXX((((3333TTTTccccllll)))) TTTTccccllllXXXX((((3333TTTTccccllll)))) This command overrides the standard Tcl procedure of the same name. llllooooaaaaddddlllliiiibbbbiiiinnnnddddeeeexxxx _l_i_b_f_i_l_e._t_l_i_b Load the package library index of the library file lllliiiibbbbffffiiiilllleeee (which must have the suffix ._t_l_i_b). Package library indexes along the aaaauuuuttttoooo____ppppaaaatttthhhh are loaded automatically on the first ddddeeeemmmmaaaannnndddd____llllooooaaaadddd; this command is provided to explicitly load libraries that are not in the path. If the index file (with a ._t_n_d_x 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 _l_i_b_f_i_l_e._t_l_i_b 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 _l_i_b_f_i_l_e._t_l_i_b will not be loaded. This command will also load an index built by mmmmkkkkiiiinnnnddddeeeexxxx....ttttccccllll program supplied with standard Tcl. This file must be named "ttttccccllllIIIInnnnddddeeeexxxx". aaaauuuuttttoooo____ppppaaaacccckkkkaaaaggggeeeessss ?-_l_o_c_a_t_i_o_n? Returns a list of the names of all defined packages. If -_l_o_c_a_t_i_o_n is specified, a list of pairs of package name and the ....ttttlllliiiibbbb path name, offset and length of the package within the library. aaaauuuuttttoooo____llllooooaaaadddd____ffffiiiilllleeee _f_i_l_e Source a file, as with the ssssoooouuuurrrrcccceeee command, except search aaaauuuuttttoooo____ppppaaaatttthhhh for the file. sssseeeeaaaarrrrcccchhhhppppaaaatttthhhh _p_a_t_h _f_i_l_e 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. PPPPaaaaggggeeee 44441111 
