Tcl provides several methods to read from and write to files on disk. The simplest methods to access a file are via gets and puts. When there is a lot of data to be read, however, it is sometimes more efficient to use the read command to load an entire file or a large chunk of it, and then parse the file into lines with the split command.
These methods can also be used for communicating over sockets and pipes. It is even possible, via the so-called virtual file system, to use files stored in memory rather than on disk. Tcl provides an almost uniform interface to these very different resources, so that in general you do not need to concern yourself with the details.
open fileName ?access? ?permissions?
Opens a file and returns a token to be used when accessing the file via gets, puts, close, etc.
fileName is the name of the file to open.
access is the file access mode
Mode
Meaning
r
Open the file for reading. The file must already exist.
r+
Open the file for reading and writing. The file must already exist.
w
Open the file for writing. Create the file if it doesn't exist, or set the length to zero if it does exist.
w+
Open the file for reading and writing. Create the file if it doesn't exist, or set the length to zero if it does exist.
a
Open the file for writing. The file must already exist. Set the current location to the end of the file.
a+
Open the file for reading and writing. Create the file if it does not exist. Set the current location to the end of the file.
permissions is an integer used to set the file access permissions (most useful under Linux and other UNIX-like systems). The default is rw-r--r-- (0644). You can use it to set the permissions for the file's owner, the group he/she belongs to and for all the other users. For many applications, the default is fine.
close fileID
Closes a file previously opened with open, and flushes any remaining output.
gets fileID ?varName?
Reads a line of input from fileID, and discards the terminating newline. If there is a varName argument, gets returns the number of characters read (or -1 if an EOF occurs), and places the line of input in varName. If varName is not specified, gets returns the line of input. An empty string will be returned if
There is a blank line in the file
The current location is at the end of the file (an EOF occurs)
A typical loop to read the file line-by-line:
set infile [open "myfile.txt"]
while { [gets $infile line] >= 0 } {
...
}
puts ?-nonewline? ?fileID? string
Writes the characters in string to the stream referenced by fileID, where fileID is one of:
The value returned by a previous call to open with write access
stdout (standard output, the screen mostly)
stderr (standard error, also the screen)
read ?-nonewline? fileID
Reads all the remaining bytes from fileID, and returns that string. If -nonewline is set, then the last character will be discarded if it is a newline. Any existing end-of-file condition is cleared before the read command is executed.
read fileID numBytes
Reads up to numBytes from fileID, and returns the input as a Tcl string. Any existing end-of-file condition is cleared before the read command is executed.
seek fileID offset ?origin?
Change the current position within the file referenced by fileID. Note that if the file was opened with a access, the current position cannot be set before the end of the file for writing. If it was opened with a+ access, however, it can be set to the beginning of the file for reading.
fileID is one of:
a file identifier returned by open
stdin (standard input, the keyboard mostly)
stdout
stderr
offset is the offset in bytes at which the current position is to be set. The position from which the offset is measured defaults to the start ofthe file, but can be from the current location, or the end by setting origin appropriately.
origin is the position to measure offset from. It defaults to the start of the file. origin must be one of:
start - the offset is measured from the start of the file.
current - the offset is measured from the current position in the file.
end - the offset is measured from the end of the file.
tell fileID
Returns the position of the access pointer in fileID.
flush fileID
Flushes any output that has been buffered for fileID.
eof fileID
Returns 1 if an End Of File condition exists, otherwise returns 0.
Points to remember about Tcl file access:
The file I/O is buffered. The output may not be sent out when you expect it to be sent. Files will all be closed and flushed when your program exits normally, but may only be closed (not flushed) if the program is terminated in an unexpected manner.
There are a finite number of open file slots available. While the exact number depends on the operating system you are using and its configuration, in practice you can have several hundreds of open files at a time. If you need more than that, you may need to reexamine your program.
An empty line is indistinguishable from an EOF with the command set string [gets filename]. Use the eof command to determine if the file is at the end or use the other form of gets (see the example).
You can't overwrite any data in a file that was opened with a (append) access. You can, however, seek to the beginning of the file for gets commands.
Opening a file with the w+ access will allow you to overwrite data, but will delete all existing data in the file.
Opening a file with the r+ access will allow you to overwrite data, while saving the existing data in the file.
By default the commands assume that strings represent "readable" text. If you want to read "binary" data, you will have to use the fconfigure command.
Often, especially if you deal with configuration data for your programs, you can use the source command instead of the relatively low-level commands presented here. Just make sure your data can be interpreted as Tcl commands and "source" the file.
Note: Since Tcl 8.5 many of the I/O features are also available via the chan command.
Example
#
# Count the number of lines in a text file
#
set infile [open "myfile.txt" r]
set number 0
#
# gets with two arguments returns the length of the line,
# -1 if the end of the file is found
# and, in this case, places the line of input into a
# variable named "line".
#
while { [gets $infile line] >= 0 } {
incr number
}
close $infile
puts "Number of lines: $number"
#
# Also report it in an external file
#
set outfile [open "report.out" w]
puts $outfile "Number of lines: $number"
close $outfile