The exec command runs programs from your Tcl script.^[*] For example:

set d [exec date]

The standard output of the program is returned as the value of the exec command. However, if the program writes to its standard error channel or exits with a nonzero status code, then exec raises an error. If you do not care about the exit status, or you use a program that insists on writing to standard error, then you can use catch to mask the errors:

catch {exec program arg arg} result

The exec command supports a full set of I/O redirection and pipeline syntax. Each process normally has three I/O channels associated with it: standard input, standard output, and standard error. With I/O redirection, you can divert these I/O channels to files or to I/O channels you have opened with the Tcl open command. A pipeline is a chain of processes that have the standard output of one command hooked up to the standard input of the next command in the pipeline. Any number of programs can be linked together into a pipeline.

set n [exec sort < /etc/passwd | uniq | wc -l 2> /dev/null]

Example 9-1 uses exec to run three programs in a pipeline. The first program is sort, which takes its input from the file /etc/passwd. The output of sort is piped into uniq, which suppresses duplicate lines. The output of uniq is piped into wc, which counts the lines. The error output of the command is diverted to the null device to suppress any error messages. Table 9-1 provides a summary of the syntax understood by the exec command.

A trailing & causes the program to run in the background. In this case, the process identifier is returned by the exec command. Otherwise, the exec command blocks during execution of the program, and the standard output of the program is the return value of exec. The trailing newline in the output is trimmed off, unless you specify -keepnewline as the first argument to exec.

If you look closely at the I/O redirection syntax, you'll see that it is built up from a few basic building blocks. The basic idea is that | stands for pipeline, > for output, and < for input. The standard error is joined to the standard output by &. Standard error is diverted separately by using 2>. You can use your own I/O channels by using @.

ls

exec ls

set auto_noexec anything

package require Tclapplescript
AppleScript junk
=> bad option "junk": must be compile, decompile, delete, execute, info, load, run, or store.

The file command provides several ways to check the status of files in the file system. For example, you can find out if a file exists, what type of file it is, and other file attributes. There are facilities for manipulating files in a platform-independent manner. Table 9-2 provides a summary of the various forms of the file command. They are described in more detail later. Note that several operations have been added since the introduction of the file command; the table indicates the version of Tcl in which they were added.

Files are named differently on UNIX, Windows, and Macintosh. UNIX separates file name components with a forward slash (/), Macintosh separates components with a colon (:), and Windows separates components with a backslash (). In addition, the way that absolute and relative names are distinguished is different. For example, these are absolute pathnames for the Tcl script library (i.e., $tcl_library) on Macintosh, Windows, and UNIX, respectively:

Disk:System Folder:Extensions:Tool Command Language:tcl7.6
c:Program FilesTcllibTcl7.6
/usr/local/tcl/lib/tcl7.6

The good news is that Tcl provides operations that let you deal with file pathnames in a platform-independent manner. The file operations described in this chapter allow either native format or the UNIX naming convention. The backslash used in Windows pathnames is especially awkward because the backslash is special to Tcl. Happily, you can use forward slashes instead:

c:/Program Files/Tcl/lib/Tcl7.6

There are some ambiguous cases that can be specified only with native pathnames. On my Macintosh, Tcl and Tk are installed in a directory that has a slash in it. You can name it only with the native Macintosh name:

Disk:Applications:Tcl/Tk 4.2

Another construct to watch out for is a leading // in a file name. This is the Windows syntax for network names that reference files on other computers. You can avoid accidentally constructing a network name by using the file join command described next. Of course, you can use network names to access remote files.

If you must communicate with external programs, you may need to construct a file name in the native syntax for the current platform. You can construct these names with file join described later. You can also convert a UNIX-like name to a native name with file nativename.

Several of the file operations operate on pathnames as opposed to returning information about the file itself. You can use the dirname, extension, join, normalize, pathtype, rootname, split, and tail operations on any string; there is no requirement that the pathnames refer to an existing file.

Building up Pathnames: file join

You can get into trouble if you try to construct file names by simply joining components with a slash. If part of the name is in native format, joining things with slashes will result in incorrect pathnames on Macintosh and Windows. The same problem arises when you accept user input. The user is likely to provide file names in native format. For example, this construct will not create a valid pathname on the Macintosh because $tcl_library is in native format:

set file $tcl_library/init.tcl

Note

Use file join to construct file names.

The platform-independent way to construct file names is with file join. The following command returns the name of the init.tcl file in native format:

set file [file join $tcl_library init.tcl]

file join a b/c d
=> a/b/c/d
file join a /b/c d
=> /b/c/d

On Macintosh, a relative pathname starts with a colon, and an absolute pathname does not. To specify an absolute path, you put a trailing colon on the first component so that it is interpreted as a volume specifier. These relative components are joined into a relative pathname:

file join a :b:c d
=> :a:b:c:d

In the next case, b:c is an absolute pathname with b: as the volume specifier. The absolute name overrides the previous relative name:

file join a b:c d
=> b:c:d

The file join operation converts UNIX-style pathnames to native format. For example, on Macintosh you get this:

file join /usr/local/lib
=> usr:local:lib

file split "/Disk/System Folder/Extensions"
=> Disk: {System Folder} Extensions

file dirname /a/b/c
=> /a/b
file tail /a/b/c
=> c

file root /a/b.c
=> /a/b
file extension /a/b.c
=> .c

Tcl 7.6 added file operations to copy files, delete files, rename files, and create directories. In earlier versions it was necessary to exec other programs to do these things, except on Macintosh, where cp, rm, mv, mkdir, and rmdir were built in. These commands are no longer supported on the Macintosh. Your scripts should use the file command operations described below to manipulate files in a platform-independent way.

File name patterns are not directly supported by the file operations. Instead, you can use the glob command described on page 122 to get a list of file names that match a pattern.

file copy ?-force? file1 file2

file copy ?-force? file1 file2 ... directory

file copy ?-force? dir1 dir2

file mkdir dir dir ...

file mkdir /tmp/sub1/sub2

file mkdir -force oops

file link the_link the_existing_file

file delete ?-force? name name ...

file delete xyzzy -force

file rename ?-force? old new

There are several file operations that return specific file attributes: atime, executable, exists, isdirectory, isfile, mtime, owned, readable, readlink, size and type. Refer to Table 9-2 on page 108 for their function. The following command uses file mtime to compare the modify times of two files. If you have ever resorted to piping the results of ls -l into awk in order to derive this information in other shell scripts, you will appreciate this example:

proc newer { file1 file2 } {
   if {![file exists $file2]} {
      return 1
   } else {
      # Assume file1 exists
      expr {[file mtime $file1] > [file mtime $file2]}
   }
}

You can use the optional time argument to mtime and atime to set the file's time attributes, like the Unix touch command. The stat and lstat operations return a collection of file attributes. They take a third argument that is the name of an array variable, and they initialize that array with elements that contain the file attributes. If the file is a symbolic link, then the lstat operation returns information about the link itself and the stat operation returns information about the target of the link.

The array elements are listed in Table 9-3. All the element values are decimal strings, except for type, which can have the values returned by the type option. The element names are based on the UNIX stat system call. Use the file attributes command described later to get other platform-specific attributes.

Example 9-3 uses the device (dev) and inode (ino) attributes of a file to determine whether two pathnames reference the same file. These attributes are UNIX specific; they are not well defined on Windows and Macintosh.

proc fileeq { path1 path2 } {
   file stat $path1 stat1
   file stat $path2 stat2
   expr {$stat1(ino) == $stat2(ino) && 
          $stat1(dev) == $stat2(dev)}
}

The file attributes operation was added in Tcl 8.0 to provide access to platform-specific attributes. The attributes operation lets you set and query attributes. The interface uses option-value pairs. With no options, all the current values are returned.

file attributes book.doc
=> -creator FRAM -hidden 0 -readonly 0 -type MAKR

These Macintosh attributes are explained in Table 9-4. The four-character type codes used on Macintosh are illustrated on page 600. With a single option, only that value is returned:

file attributes book.doc -readonly
=> 0

The attributes are modified by specifying one or more option–value pairs. Setting attributes can raise an error if you do not have the right permissions:

file attributes book.doc -readonly 1 -hidden 0

The following sections describe how to open, read, and write files. The basic model is that you open a file, read or write it, then close the file. Network sockets also use the commands described here. Socket programming is discussed in Chapter 17, and more advanced event-driven I/O is described in Chapter 16. Table 9-5 lists the basic commands associated with file I/O:

The open command sets up an I/O channel to either a file or a pipeline of processes. The return value of open is an identifier for the I/O channel. Store the result of open in a variable and use the variable as you used the stdout, stdin, and stderr identifiers in the examples so far. The basic syntax is:

open what ?access? ?permissions?

The what argument is either a file name or a pipeline specification similar to that used by the exec command. The access argument can take two forms, either a short character sequence that is compatible with the fopen library routine, or a list of POSIX access flags. Table 9-6 summarizes the first form, while Table 9-7 summarizes the POSIX flags. If access is not specified, it defaults to read.

set fileId [open /tmp/foo w 0600]
puts $fileId "Hello, foo!"
close $fileId

The permissions argument is a value used for the permission bits on a newly created file. UNIX uses three bits each for the owner, group, and everyone else. The bits specify read, write, and execute permission. These bits are usually specified with an octal number, which has a leading zero, so that there is one octal digit for each set of bits. The default permission bits are 0666, which grant read/write access to everybody. Example 9-4 specifies 0600 so that the file is readable and writable only by the owner. 0775 would grant read, write, and execute permissions to the owner and group, and read and execute permissions to everyone else. You can set other special properties with additional high-order bits. Consult the UNIX manual page on chmod command for more details.

The following example illustrates how to use a list of POSIX access flags to open a file for reading and writing, creating it if needed, and not truncating it. This is something you cannot do with the simpler form of the access argument:

set fileId [open /tmp/bar {RDWR CREAT}]

Note

Catch errors from open.

In general, you should check for errors when opening files. The following example illustrates a catch phrase used to open files. Recall that catch returns 1 if it catches an error; otherwise, it returns zero. It treats its second argument as the name of a variable. In the error case, it puts the error message into the variable. In the normal case, it puts the result of the command into the variable:

if [catch {open /tmp/data r} fileId] {
   puts stderr "Cannot open /tmp/data: $fileId"
} else {
   # Read and process the file, then...
   close $fileId
}

set input [open "|sort /etc/passwd" r]
set contents [split [read $input] 
]
close $input

package require Expect

The standard I/O channels are already open for you. There is a standard input channel, a standard output channel, and a standard error output channel. These channels are identified by stdin, stdout, and stderr, respectively. Other I/O channels are returned by the open command, and by the socket command described on page 239.

There may be cases when the standard I/O channels are not available. The wish shells on Windows and Macintosh have no standard I/O channels. Some UNIX window managers close the standard I/O channels when you start programs from window manager menus. You can also close the standard I/O channels with close.

puts -nonewline "Enter value: "
flush stdout ;# Necessary to get partial line output
set answer [gets stdin]

while {[gets $channel line] >= 0} {
   # Process line
}
close $channel

foreach line [split [read $channel] 
] {
   # Process line
}
close $channel

puts -nonewline $out [read $in]

proc File_Copy {src dest} {
   if {[file isdirectory $src]} {
      file mkdir $dest
      foreach f [glob -nocomplain [file join $src *]] {
         File_Copy $f [file join $dest [file tail $f]]
      }
      return
   }
   if {[file isdirectory $dest]} {
      set dest [file join $dest [file tail $src]]
    }
   set in [open $src]
   set out [open $dest w]
   puts -nonewline $out [read $in]
   close $out ; close $in
}

Closing I/O Channels

The close command is just as important as the others because it frees operating system resources associated with the I/O channel. If you forget to close a channel, it will be closed when your process exits. However, if you have a long-running program, like a Tk script, you might exhaust some operating system resources if you forget to close your I/O channels.

Note

The close command can raise an error.

If the channel was a process pipeline and any of the processes wrote to their standard error channel, then Tcl believes this is an error. The error is raised when the channel to the pipeline is finally closed. Similarly, if any of the processes in the pipeline exit with a nonzero status, close raises an error.

Every process has a current directory that is used as the starting point when resolving a relative pathname. The pwd command returns the current directory, and the cd command changes the current directory. Example 9-11 uses these commands.

The glob command expands a pattern into the set of matching file names. The general form of the glob command is:

glob ?options? pattern ?pattern? ...

The pattern syntax is similar to the string match patterns:

Table 9-8 lists the options for the glob command.

Unlike the glob matching in csh, the Tcl glob command matches only the names of existing files. In csh, the {a,b} construct can match nonexistent names. In addition, the results of glob are not sorted. Use the lsort command to sort its result if you find it important.

Example 9-11 shows the FindFile procedure, which traverses the file system hierarchy using recursion. At each iteration it saves its current directory and then attempts to change to the next subdirectory. A catch guards against bogus names. The glob command matches file names:

proc FindFile { startDir namePat } {
   set pwd [pwd]
   if {[catch {cd $startDir} err]} {
      puts stderr $err
      return
   }
   foreach match [glob -nocomplain -- $namePat] {
      puts stdout [file join $startDir $match]
   }
   foreach file {[glob -nocomplain *]} {
      if [file isdirectory $file] {
         FindFile [file join $startDir $file] $namePat
      }
   }
   cd $pwd
}

The -types option allows for special filtered matching similar to the UNIX find command. The first form is like the -type option of find: b (block special file), c (character special file), d (directory), f (plain file), l (symbolic link), p (named pipe), or s (socket), where multiple types may be specified in the list. Glob will return all files which match at least one of the types given.

The second form specifies types where all the types given must match. These are r (readable), w (writable) and x (executable) as file permissions, and readonly and hidden as special cases. On the Macintosh, MacOS types and creators are also supported, where any item which is four characters long is assumed to be a MacOS type (e.g. TEXT). Items which are of the form {macintosh type XXXX} or {macintosh creator XXXX} will match types or creators respectively. Unrecognized types, or specifications of multiple MacOS types/creators will signal an error.

The two forms may be mixed, so -types {d f r w} will find all regular files OR directories that have both read AND write permissions.

The exit command terminates your script. Note that exit causes termination of the whole process that was running the script. If you supply an integer-valued argument to exit, then that becomes the exit status of the process.

The pid command returns the process ID of the current process. This can be useful as the seed for a random number generator because it changes each time you run your script. It is also common to embed the process ID in the name of temporary files.

You can also find out the process IDs associated with a process pipeline with pid:

set pipe [open "|command"]
set pids [pid $pipe]

There is no built-in mechanism to control processes in the Tcl core. On UNIX systems you can exec the kill program to terminate a process:

exec kill $pid

Environment variables are a collection of string-valued variables associated with each process. The process's environment variables are available through the global array env. The name of the environment variable is the index, (e.g., env(PATH)), and the array element contains the current value of the environment variable. If assignments are made to env, they result in changes to the corresponding environment variable. Environment variables are inherited by child processes, so programs run with the exec command inherit the environment of the Tcl script. The following example prints the values of environment variables.

proc printenv { args } {
   global env
   set maxl 0
   if {[llength $args] == 0} {
      set args [lsort [array names env]]
   }
   foreach x $args {
      if {[string length $x] > $maxl} {
         set maxl [string length $x]
      }
   }
   incr maxl 2
   foreach x $args {
      puts stdout [format "%*s = %s" $maxl $x $env($x)]
   }
}
printenv USER SHELL TERM
=>
USER  = welch
SHELL  = /bin/csh
TERM  = tx

Note: Environment variables can be initialized for Macintosh applications by editing a resource of type STR# whose name is Tcl Environment Variables. This resource is part of the tclsh and wish applications. Follow the directions on page 28 for using ResEdit. The format of the resource values is NAME=VALUE.

Windows uses the registry to store various system configuration information. The Windows tool to browse and edit the registry is called regedit. Tcl provides a registry command. It is a loadable package that you must load by using:

package require registry

The registry structure has keys, value names, and typed data. The value names are stored under a key, and each value name has data associated with it. The keys are organized into a hierarchical naming system, so another way to think of the value names is as an extra level in the hierarchy. The main point is that you need to specify both a key name and a value name in order to get something out of the registry. The key names have one of the following formats:

\hostnamerootnamekeypath
rootnamekeypath
rootname

The rootname is one of HKEY_LOCAL_MACHINE, HKEY_PERFORMANCE_DATA, HKEY_USERS, HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_CURRENT_CONFIG, or HKEY_DYN_DATA. Tables 9-9 and 9-10 summarize the registry command and data types: