TclX(3Tcl) TclX(3Tcl)
TclX - Extended Tcl: Extended command set for Tcl
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
GENERAL COMMANDS
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.
dirs This procedure lists the directories in the directory stack.
Page 1
TclX(3Tcl) TclX(3Tcl)
commandloop ?prompt1? ?prompt2?
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.
Prompt1 is a Tcl command that is evaluated to output a prompt
string. The old value of tcl_prompt1 is saved and it is set to this
value for the duration of the command loop. Prompt2 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
tcl_prompt2 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.
echo ?str ...?
Writes zero or more strings to standard output, followed by a
newline.
infox option
Return information about Extended Tcl, or the current application.
The following infox command options are available:
version
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
7.4a.
patchlevel
Return the patchlevel for Extended Tcl.
have_fchown
Return 1 if the fchown system call is available. This supports
the -fileid option on the chown and chgrp commands.
have_fchmod
Return 1 if the fchmod system call is available. This supports
the -fileid option on the chmod command.
have_flock
Return 1 if the flock command defined, 0 if it is not
available.
have_fsync
Return 1 if the fsync system call is available and the sync
command will sync individual files. 0 if it is not available
Page 2
TclX(3Tcl) TclX(3Tcl)
and the sync command will always sync all file buffers.
have_ftruncate
Return 1 if the ftruncate system call is available. If it is,
the ftruncate command -fileid option maybe used.
have_msgcats
Return 1 if XPG message catalogs are available, 0 if they are
not. The catgets is designed to continue to function without
message catalogs, always returning the default string.
have_posix_signals
Return 1 if Posix signals are available (block and unblock
options available for the signal command). 0 is returned if
Posix signals are not available.
have_sockets
Return 1 if sockets are available (server_* suite and fstat
localhost and remotehost options). 0 is returned if sockets
are not available.
have_truncate
Return 1 if the truncate of chsize system call is available.
If it is, the ftruncate command will work.
appname
Return the symbolic application name of the current application
linked with the Extended Tcl library. The C variable
tclAppName must be set by the application to return an
application specific value for this variable.
applongname
Return a natural language name for the current application. The
C variable tclLongAppName must be set by the application to
return an application specific value for this variable.
appversion
Return the version number for the current application. The C
variable tclAppVersion must be set by the application to return
an application-specific value for this variable.
apppatchlevel
Return the patchlevel for the current application. The C
variable tclAppPatchlevel must be set by the application to
return an application-specific value for this variable.
for_array_keys var array_name code
This procedure performs a foreach-style loop for each key in the
named array. The break and continue statements work as with
foreach.
Page 3
TclX(3Tcl) TclX(3Tcl)
for_recursive_glob var dirlist globlist code
This procedure performs a foreach-style loop over recursively
matched files. All directories in dirlist are recursively searched
(breadth-first), comparing each file found against the file glob
patterns in globlist. For each matched file, the variable var is
set to the file path and code is evaluated. Symbolic links are not
followed.
loop var first limit ?increment? body
Loop is a looping command, similar in behavior to the Tcl for
statement, except that the loop statement achieves substantially
higher performance and is easier to code when the beginning and
ending values of a loop are known, and the loop variable is to be
incremented by a known, fixed amount every time through the loop.
The var argument is the name of a Tcl variable that will contain
the loop index. The loop index is set to the value specified by
first. The Tcl interpreter is invoked upon body zero or more times,
where var is incremented by increment every time through the loop,
or by one if increment is not specified. Increment can be negative
in which case the loop will count downwards.
When var reaches limit, the loop terminates without a subsequent
execution of body. For instance, if the original loop parameters
would cause loop to terminate, say first was one, limit was zero and
increment was not specified or was non-negative, body is not
executed at all and loop returns.
The first, limit and increment are integer expressions. They are
only evaulated once at the beginning of the loop.
If a continue command is invoked within body then any remaining
commands in the current execution of body are skipped, as in the for
command. If a break command is invoked within body then the loop
command will return immediately. Loop returns an empty string.
popd
This procedure pops the top directory entry from the directory stack
and make it the current directory.
pushd ?dir?
This procedure pushs the current directory onto the directory stack
and cd to the specified directory. If the directory is not
specified, then the current directory is pushed, but remains
unchanged.
recursive_glob dirlist globlist
This procedure returns a list of recursively matches files. All
directories in dirlist are recursively searched (breadth-first),
comparing each file found against the file glob patterns in
globlist. Symbolic links are not followed.
Page 4
TclX(3Tcl) TclX(3Tcl)
showproc ?procname ...?
This procedure lists the definition of the named procedures.
Loading them if it is not already loaded. If no procedure names are
supplied, the definitions of all currently loaded procedures are
returned.
This section contains information on commands and procdures that are
useful for developing and debugging Tcl scripts.
cmdtrace level|on ?noeval? ?notruncate? ?procs? ?fileid?
Print a trace statement for all commands executed at depth of level
or below (1 is the top level). If on is specified, all commands at
any level are traced. The following options are available:
noeval
Causes arguments to be printed unevaluated. If noeval 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.
notruncate
Disables the truncation of commands and evaluated arguments.
procs
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 procs option is specified. This option is particularly
useful for greatly reducing the output of cmdtrace while
debugging.
fileid
This is a file id as returned by the open 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:
Page 5
TclX(3Tcl) TclX(3Tcl)
cmdtrace on [open cmd.log w]
cmdtrace off
Turn off all tracing.
cmdtrace depth
Returns the current maximum trace level, or zero if trace is
disabled.
edprocs ?proc...?
This procedure writes the named procedures, or all currently defined
procedures, to a temporary file, then calls an editor on it (as
specified by the EDITOR environment variable, or vi if none is
specified), then sources the file back in if it was changed.
profile ?-commands? on
profile off arrayVar
This command is used to collect a performance profile of a Tcl
script. It collects data at the Tcl procedure level. The number of
calls to a procedure, and the amount of real and CPU time is
collected. Time is also collected for the global context. The
procedure data is collected by bucketing it based on the procedure
call stack, this allows determination of how much time is spent in a
particular procedure in each of it's calling contexts.
The on option enables profile data collection. If the -commands
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 off option turns off profiling and moves the data collected to
the array arrayVar. 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 {count real cpu}. A Tcl procedure
profrep is supplied for reducing the data and producing a report
profrep profDataVar sortKey ?outFile? ?userTitle?
This procedure generates a report from data collect from the profile
command. ProfDataVar is the name of the array containing the data
returned by the profile command. SortKey indicates which data value
to sort by. It should be one of "calls", "cpu" or "real". OutFile
is the name of file to write the report to. If omitted, stdout is
assumed. UserTitle is an optional title line to add to output.
saveprocs fileName ?proc...?
This prodcure saves the definition of the named procedure, or all
currently defined procedures if none is specified, to the named
Page 6
TclX(3Tcl) TclX(3Tcl)
file.
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.
alarm seconds
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 seconds is 0.0, any previous alarm
request is canceled. Only one alarm at a time may be active; the
command returns the number of seconds left in the previous alarm.
On systems without the setitimer system call, seconds is rounded up
to an integer number of seconds.
convertclock dateString ?GMT|{}? ?baseClock?
Convert dateString to an integer clock value (see getclock). 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 GMT argument is specified, in which case the
clock value is calculated assuming that the specified time is
relative to Greenwich Mean Time.
If baseClock 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 daterelative
conversions.
The character string consists of zero or more specifications of the
following form:
time - A time of day, which is of the form hh[:mm[:ss]] [meridian]
[zone] or hhmm [meridian] [zone]. If no meridian is specified, hh
is interpreted on a 24-hour clock.
date - A specific month and day with optional year. The acceptable
formats are mm/dd[/yy], monthname dd[, yy], dd monthname [yy], and
day, dd monthname yy. The default year is the current year. If the
year is less then 100, then 1900 is added to it.
relative time - A specification relative to the current time. The
format is number unit; acceptable units are year, fortnight, month,
week, day, hour, minute (or min), and second (or sec). The unit can
be specified as a singular or plural, as in 3 weeks. These
modifiers may also be specified: tomorrow, yesterday, today, now,
last, this, next, ago.
The actual date is calculated according to the following steps.
First, any absolute date and/or time is processed and converted.
Page 7
TclX(3Tcl) TclX(3Tcl)
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.
convertclock 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 convertclock 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"
execl ?-argv0 argv0? prog ?arglist?
Do an execl, replacing the current program (either Extended Tcl or
an application with Extended Tcl embedded into it) with prog and
passing the arguments in the list arglist.
The -argv0 options specifies that argv0 is to be passed to the
program as argv [0] rather than prog.
Note: If you are using execl in a Tk application and it fails, you
may not do anything that accesses the X server or you will receive a
BadWindow error from the X server. This includes executing the Tk
version of the exit command. We suggest using the following command
to abort Tk applications after an execl failure:
kill [id process]
fmtclock clockval ?format? ?GMT|{}?
Converts a Unix integer time value, typically returned by getclock,
convertclock, or the atime, mtime, or ctime options of the file
command, to human-readable form. The format 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
Page 8
TclX(3Tcl) TclX(3Tcl)
%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
GMT 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.
chroot dirname
Change root directory to dirname, by invoking the POSIX chroot(2)
system call. This command only succeeds if running as root.
fork
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 execl is not going to be performed before the child process
does output, or if a close and dup sequence is going to be performed
on stdout or stderr, then a flush should be issued against stdout,
stderr and any other open output file before doing the fork.
Otherwise characters from the parent process pending in the buffers
will be output by both the parent and child processes.
Note: If you are forking in a Tk based apllication you must execl
before doing any window operations in the child or you will receive
Page 9
TclX(3Tcl) TclX(3Tcl)
a BadWindow error from the X server.
getclock
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.
id options
This command provides a means of getting, setting and converting
user, group and process ids. The id command has the following
options:
id user ?NAME?
id userid ?uid?
Set the real and effective user ID to NAME or uid, if the name
(or uid) is valid and permissions allow it. If the name (or
uid) is not specified, the current name (or uid) is returned.
id convert userid uid
id convert user NAME
Convert a user ID number to a user name, or vice versa.
id group ?NAME?
id groupid ?gid?
Set the real and effective group ID to NAME or gid, if the name
(or gid) is valid and permissions allow it. If the group name
(or gid) is not specified, the current group name (or gid) is
returned.
id groups
id groupids
Return the current group access list of the process. The
option groups returns group names and groupids returns id
numbers.
id convert groupid gid
id convert group NAME
Convert a group ID number to a group name, or vice versa.
id effective user
id effective userid
Return the effective user name, or effective user ID number,
respectively.
Page 10
TclX(3Tcl) TclX(3Tcl)
id effective group
id effective groupid
Return the effective group name, or effective group ID number,
respectively.
id effective groupids
Return all of the groupids the user is a member of.
id host
Return the hostname of the system the program is running on.
id process
Return the process ID of the current process.
id process parent
Return the process ID of the parent of the current process.
id process group
Return the process group ID of the current process.
id process group set
Set the process group ID of the current process to its process
ID.
id host
Returns the standard host name of the machine the process is
executing on.
kill ?-pgroup? ?signal? idlist
Send a signal to the each process in the list idlist, if permitted.
Signal, if present, is the signal number or the symbolic name of the
signal, see the signal system call manual page. The leading ``SIG''
is optional when the signal is specified by its symbolic name. The
default for signo is 15, SIGTERM.
If -pgroup is specified, the numbers in idlist are take as process
group ids and the signal is sent to all of the process in that
process group. A process group id of 0 specifies the current
process group.
link ?-sym? srcpath destpath
Create a directory entry, destpath, linking it to the existing file,
srcpath. If -sym is specified, a symbolic link, rather than a hard
link, is created. (The -sym option is only available on systems
that support symbolic links.)
mkdir ?-path? dirList
Create each of the directories in the list dirList. The mode on the
new directories is 777, modified by the umask. If -path is
specified, then any non-existent parent directories in the specified
path(s) are also created.
Page 11
TclX(3Tcl) TclX(3Tcl)
nice ?priorityincr?
Change or return the process priority. If priorityincr is omitted,
the current priority is returned. If priorityincr is positive, it
is added to the current priority level, up to a system defined
maximum (normally 19),
Negative priorityincr values cumulatively increase the program's
priority down to a system defined minimum (normally -19); increasing
priority with negative niceness values will only work for the
superuser.
The new priority is returned.
readdir dirPath
Returns a list containing the contents of the directory dirPath.
The directory entries "." and ".." are not returned.
rmdir ?-nocomplain? dirList
Remove each of the directories in the list dirList. If -nocomplain
is specified, then errors will be ignored.
signal action siglist ?command?
Specify the action to take when a Unix signal is received by
Extended Tcl, or a program that embeds it. Siglist is a list of
either the symbolic or numeric Unix signal (the SIG prefix is
optional). Action is one of the following actions to be 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).
default - Perform system default action when signal is received (see
signal system call documentation).
ignore - Ignore the signal.
error - 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:
POSIX SIG signame
For the death of child signal, signame will always be SIGCHLD,
rather than SIGCLD, to allow writing portable code.
trap - When the signal occurs, execute command and continue
execution if an error is not returned by command. 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
command will just do an exit.
Page 12
TclX(3Tcl) TclX(3Tcl)
get - 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 0 if the signal may be delivered (not block) and
a 1 if it is blocked. The actions maybe one of `default',`ignore',
`error' or `trap. If the action is trap, the third element is the
command associated with the action. The action `unknown' is
returned if a non-Tcl signal handler has been associated with the
signal.
set - Set signals from a keyed list in the format returned by the
get. For this action, siglist is the keyed list of signal state.
Signals with an action of `unknown' are not modified.
block - Block the specified signals from being received. (Posix
systems only).
unblock - 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 SIGCHLD on systems without Posix
signals. For these systems, SIGCHLD is not be automatically
reenabled. After a SIGCHLD signal is received, a call to wait must
be performed to retrieve the exit status of the child process before
issuing another signal SIGCHLD ... 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 SIGINT will be set to
error, non-interactive Tcl sessions leave SIGINT unchanged from when
the process started (normally default for foreground processes and
ignore for processes in the background).
sleep seconds
Sleep the Extended Tcl process for seconds seconds.
system command
Executes command via the system(3) call. Differs from exec in that
system doesn't return the executed command's standard output as the
result string, and system goes through the Unix shell to provide
wildcard expansion, redirection, etc, as is normal from an sh
command line. The exit code of the command is returned.
sync ?fileId?
If fileId is not specified, or if it is and this system does not
support the fsync system call, issues a sync system call to flush
all pending disk output. If fileId is specified and the system does
support the fsync system call, issues an fsync on the file
corresponding to the specified Tcl fileId to force all pending
output to that file out to the disk.
Page 13
TclX(3Tcl) TclX(3Tcl)
If fileId is specified, the file must be writable. A flush will be
issued against the fileId before the sync.
The infox have_fsync command can be used to determine if "sync
fileId" will do a sync or a fsync.
times
Return a list containing the process and child execution times in
the form:
utime stime cutime cstime
Also see the times(2) system call manual page. The values are in
milliseconds.
umask ?octalmask?
Sets file-creation mode mask to the octal value of octalmask. If
octalmask is omitted, the current mask is returned.
unlink ?-nocomplain? filelist
Delete (unlink) the files whose names are in the list filelist. If
-nocomplain is specified, then errors will be ignored.
wait ?-nohang? ?-untraced? ?-pgroup? ?pid?
Waits for a process created with the execl command to terminate,
either due to an untrapped signal or call to exit system call. If
the process id pid is specified, they wait on that process,
otherwise wait on any child process to terminate.
If -nohang is specified, then don't block waiting on a process to
terminate. If no process is immediately available, return an empty
list. If -untraced 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 -pgroup is specfied and pid is
not specified, then wait on any child process whose process groupd
ID is they same as the calling process. If pid is specified with
-pgroup, then it is take as a process group ID, waiting on any
process in that process group to terminate.
Wait 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 exec command. However, if any
other exec command is executed after the process terminates, then
the process status will be reaped by the exec command and will not
be available to the wait command.
Page 14
TclX(3Tcl) TclX(3Tcl)
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 pipe system call. Also linking and
unlinking files, setting file, process, and user attributes and
truncating files. An interface to the select 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 flush command should be issued to force the
data out. Alternatively, the fcntl command may be used to set the
buffering mode of a file to line-buffered or unbuffered.
bsearch fileId key ?retvar? ?compare_proc?
Search an opened file fileId containing lines of text sorted into
ascending order for a match. Key contains the string to match. If
retvar is specified, then the line from the file is returned in
retvar, and the command returns 1 if key was found, and 0 if it
wasn't. If retvar is not specified or is a null name, then the
command returns the line that was found, or an empty string if key
wasn't found.
By default, the key is matched against the first white-space
separated field in each line. The field is treated as an ASCII
string. If compare_proc 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 bsearch command. Compare_proc
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
compare_proc uses to compare the key with the line, or errouenous
results will occur.
copyfile ?-bytes num|-maxbytes num? fromFileId toFileId
Copies the rest of the file specified by fromFileId, starting from
its current position, to the file specified by toFileId, starting
from its current position.
If -bytes is specified, then num bytes are copied. If less than num
bytes are available, an error is returned. If -maxbytes is
specified, then num bytes are copied but no error is returned if
less are available.
The command returns the number of bytes that were copied.
The -bytes option is particularly useful for mixing binary data in
with ASCII commands or data in a data stream.
Page 15
TclX(3Tcl) TclX(3Tcl)
chmod [-fileid] mode filelist
Set permissions of each of the files in the list filelist to mode,
where mode is an absolute numeric mode or symbolic permissions as in
the UNIX chmod(1) command. To specify a mode as octal, it should be
prefixed with a "0" (e.g. 0622).
If the option -fileid is specified, filelist is a list of open file
identifiers rather than a list of file names. This option is not
available on all Unix systems. Use the infox have_fchmod command to
determine if this functionallity is available.
chown [-fileid] owner|{owner group} filelist
Set owner of each file in the list filelist to owner, which can be a
user name or numeric user id. If the first parameter is a list,
then the owner is set to the first element of the list and the group
is set to the second element. Group can be a group name or numeric
group id. If group is {}, then the file group will be set to the
login group of the specified user.
If the option -fileid is specified, filelist is a list of open file
identifiers rather than a list of file names. This option is not
available on all Unix systems. Use the infox have_fchown command to
determine if this functionallity is available.
chgrp [-fileid] group filelist
Set the group id of each file in the list filelist to group, which
can be either a group name or a numeric group id.
If the option -fileid is specified, filelist is a list of open file
identifiers rather than a list of file names. This option is not
available on all Unix systems. Use the infox have_fchown command to
determine if this functionallity is available.
dup fileId ?targetFileId?
Duplicate an open file. A new file id is opened that addresses the
same file as fileId.
If targetFileId is specified, the the file is dup to this specified
file id. Normally this is stdin, stdout, or stderr. 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 fcntl
command to set it unbuffered.
If fileId is a number rather than a Tcl file id, then the dup
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 ?targetFileId? is not valid with this operation.
fcntl fileId attribute ?value?
This command either sets or clears a file option or returns its
current value. If value are not specified, then the current value
of attribute is returned. The following attributes may be specified:
Page 16
TclX(3Tcl) TclX(3Tcl)
RDONLY - The file is opened for reading only. (Get only)
WRONLY - The file is opened for writing only. (Get only)
RDWR - The file is opened for reading and writing. (Get only)
READ - If the file is readable. (Get only).
WRITE - If the file is writable. (Get only).
APPEND - The file is opened for append-only writes. All writes will
be forced to the end of the file.
NONBLOCK - The file is to be accessed with non-blocking I/O. See
the read system call for a description of how it affects the
behavior of file reads.
CLOEXEC - Close the file on an process exec. If the execl command
or some other mechanism causes the process to do an exec, the file
will be closed if this option is set.
NOBUF - The file is not buffered. If set, then there no stdio
buffering for the file.
LINEBUF - 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 APPEND, NONBLOCK, and CLOEXEC attributes may be set or cleared
by specifying the attribute name and a value 1 to set the attribute
and 0 to clear it.
The NOBUF and LINEBUF attributes may only be set (a value of 1) 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.
flock options fileId ?start? ?length? ?origin?
This command places a lock on all or part of the file specified by
fileId. The lock is either advisory or mandatory, depending on the
mode bits of the file. The lock is placed beginning at relative
byte offset start for length bytes. If start or length is omitted
or empty, zero is assumed. If length is zero, then the lock always
extents to end of file, even if the file grows. If origin is
"start", then the offset is relative to the beginning of the file.
If it is "current", it is relative to the current access position in
the file. If it is "end", then it is relative to the end-of-file (a
negative is before the EOF, positive is after). If origin is
omitted, start is assumed.
The following options are recognized:
Page 17
TclX(3Tcl) TclX(3Tcl)
-read - Place a read lock on the file. Multiple processes may be
accessing the file with read-locks.
-write - Place a write lock on the file. Only one process may be
accessing a file if there is a write lock.
-nowait - 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 fcntl 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 fcntl
command).
for_file var filename { code }
This procedure implements a loop over the contents of a file. For
each line in filename, it sets var to the line and executes code.
The break and continue commands work as with foreach.
For example, the command
for_file line /etc/passwd {echo $line}
would echo all the lines in the password file.
funlock fileId ?start? ?length? ?origin?
Remove a locked from a file that was previously placed with the
flock command. The arguments are the same as for the flock command,
see that command for more details.
fstat fileId ?item?|?stat arrayvar?
Obtain status information about an open file.
The following keys are used to identify data items:
o atime - The time of last access.
o ctime - The time of last file status change
o dev - The device containing a directory for the file. This value
uniquely identifies the file system that contains the file.
o gid - The group ID of the file's group.
o ino - The inode number. This field uniquely identifies the file
in a given file system.
o mode - The mode of the file (see the mknod system call).
Page 18
TclX(3Tcl) TclX(3Tcl)
o mtime - Time when the data in the file was last modified.
o nlink - The number of links to the file.
o size - The file size in bytes.
o tty - If the file is associated with a terminal, then 1 otherwise
0.
o type - The type of the file in symbolic form, which is one of the
following values: file, directory, characterSpecial, blockSpecial,
fifo, link, or socket.
o uid - The user ID of the file's owner.
If one of these keys is specified as item, then that data item is
returned.
If stat arrayvar is specified, then the information is returned in
the array arrrayvar. Each of the above keys indexes an element of
the array containing the data.
If only fileId is specified, the command returns the data as a keyed
list.
The following values may be returned only if explicitly asked for,
it will not be returned with the array or keyed list forms:
o remotehost - If fileId is a TCP/IP socket connection, then a list
is returned with the first element being the remote host IP address.
If the remote host name can be found, it is returned as the second
element of the list. The remote host IP port number is returned as
the this element.
o localhost - If fileId is a TCP/IP socket connection, then a list
is returned with the first element being the local host IP address.
If the local host name can be found, it is returned as the second
element of the list. The local host IP port number is returned as
the this element.
ftruncate [-fileid] file newsize
Truncate a file to have a length of at most newsize bytes.
If the option -fileid is specified, file 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 infox
have_truncate will indicate if this command is available. On some
systems, the -fileid option is not available, check the result of
infox have_ftruncate to see if it can be used.
Page 19
TclX(3Tcl) TclX(3Tcl)
lgets fileId ?varName?
Reads the next Tcl list from the file given by fileId and discards
the terminating newline character. This command differs from the
gets 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 puts will do this correctly. If varName is
specified, then the line is placed in the variable by that name and
the return value is a count of the number of characters read (not
including the newline). If the end of the file is reached before
reading any characters then -1 is returned and varName is set to an
empty string. If varName is 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 eof may have to be used to determine what
really happened.
frename oldPath newPath
Renames oldPath to newPath. This command does not support renaming
across file systems.
pipe ?fileId_var_r fileId_var_w?
Create a pipe. If fileId_var_r and fileId_var_r are specified, then
pipe will set the a variable named fileId_var_r to contain the
fileId of the side of the pipe that was opened for reading, and
fileId_var_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.
read_file ?-nonewline? fileName
read_file fileName numBytes
This proecure reads the file fileName and returns the contents as a
string. If -nonewline 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 numBytes bytes left in the file; in this case, all the
remaining bytes are returned.
select readfileIds ?writefileIds? ?exceptfileIds? ?timeout?
This command allows an Extended Tcl program to wait on zero or more
files being ready for for reading, writing, have an exceptional
condition pending, or for a timeout period to expire. readFileIds,
writeFileIds, exceptFileIds are each lists of fileIds, as returned
from open, to query. An empty list ({}) may be specified if a
category is not used.
The files specified by the readFileIds list are checked to see if
data is available for reading. The writeFileIds are checked if the
Page 20
TclX(3Tcl) TclX(3Tcl)
specified files are clear for writing. The exceptFileIds 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.
Timeout is a floating point timeout value, in seconds. If an empty
list is supplied (or the parameter is omitted), then no timeout is
set. If the value is zero, then the select command functions as a
poll of the files, returning immediately even if none are ready.
If the timeout period expires with none of the files 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 {} {}
write_file fileName string ?string...?
This procedure writes the specified strings to the named file.
TCP/IP SERVER ACCESS
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 inetd, or
even servers that run standalone and accept and manage multiple
simultaneous connections. The socket file handles maybe be read using
the either the gets or read command and written using either the puts or
server_send command.
The fstat remotehost and fstat localhost requests are useful both for
clients and servers. To obtain the host name of the system the script is
running on, use id host.
If a TclX script is setup to run under inetd, it is launched with its
stdin, stdout and stderr associated with the client socket. The standard
Tcl file ids stdin, stdout and stderr maybe then be used to communicate
with the client.
Page 21
TclX(3Tcl) TclX(3Tcl)
server_connect ?options? host service
Open a TCP/IP connection to a server of host on the port specified
by service. The server is then accessed using the standard Tcl file
I/O commands. Host may be a host name or an IP address. Port 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 server_info command to obtain the list of valid
address.
The options are:
o -buf - Specifies that the file is buffered. When writing to the
file, the flush 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 gets,
read, and puts commands. The server_send command does not use the
buffer.
o -nobuf - The file is unbuffered. A single file id, open for both
reading and writing, is returned.
o -twoids - Return a pair of file ids in a list. The first id is
open for read access, the second for write access. The close
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 -myip ipNumber - 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 -myip is not
specified, the operating system will assign the IP number for you.
o -myport portNumber - 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.
server_create ?options?
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 server_accept.
Page 22
TclX(3Tcl) TclX(3Tcl)
The file handle can be detected as read-ready using select, by using
fcntl to make the handle nonblocking and then calling server_accept,
or by using the Tk fileevent command.
Options are:
o -myip ipNumber - 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 -myip is not
specified, the operating system will assign the IP number for you.
o -myport portNumber - 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 -backlog count - 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 ECONNREFUSED,
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.
server_accept ?options? fileid
Accept a TCP/IP connection to the server socket associated with
fileid. Options are -buf, -nobuf and -twoids. See the
server_connect command for a description of these options. A file
handle (or a pair of file handles when -twoids) is return.
server_info addresses host
server_info official_name host
server_info aliases host
Optain information about a TCP/IP server. The argument host can be
either a host name or an IP address.
The following subcommands are recognized:
o addresses - Return the list of IP addresses for host.
o official_name - Return official name for host.
o aliases - Return the list of aliases for host. (Note that these
are IP number aliases, not DNS CNAME aliases. See ifconfig(2).)
server_send ?options? fileid string
Send the specified string to the TCP/IP connection corresponding to
fileid. Theserver_send command is provide as an option to puts for
writing to a socket as it is better at detecting lost connections
Page 23
TclX(3Tcl) TclX(3Tcl)
and other IP-related error conditions. File buffering is ignored
for server_send. There is no need to flush after a server_send. The
results of mixing server_send with puts without flushing the puts
output is indeterminate.
Options are:
o -nonewline - Don't append a newline character to the end of the
message. The default is to append a newline character.
o -dontroute - Requests that routing be bypassed and the direct
interface used (usually used only by diagnostic or routing programs)
o -outofband - Send out-of-band data on the socket.
FILE SCANNING COMMANDS [Toc] [Back] These commands provide a facility to scan files, matching lines of the
file against regular expressions and executing Tcl code on a match. With
this facility you can use Tcl to do the sort of file processing that is
traditionally done with awk. And since Tcl's approach is more
declarative, some of the scripts that can be rather difficult to write in
awk are simple to code in Tcl.
File scanning in Tcl centers around the concept of a scan context. A
scan context contains one or more match statements, which associate
regular expressions to scan for with Tcl code to be executed when the
expressions are matched.
scancontext ?option?
This command manages file scan contexts. A scan context is a
collection of regular expressions and commands to execute when that
regular expression matches a line of the file. A context may also
have a single default match, to be applied against lines that do not
match any of the regular expressions. Multiple scan contexts may be
defined and they may be reused on multi
|
