TIP 603: Get 'stat' Information of Open Files

Bounty program for improvements to Tcl and certain Tcl packages.
Author:         Donal K. Fellows <[email protected]>
State:          Draft
Type:           Project
Vote:           Pending
Created:        19-Jun-2021
Keywords:       Tcl, file
Tcl-Version:    8.7
Tcl-Branch:     tip-603


This TIP proposes adding the ability to get information such as is produced by file stat for an open file. This has security advantages.


With symbolic links and the ability to make substantial changes to a directory after a file in it is opened, it is necessary to sometimes be able to determine exact file information about a file that has already been opened. This has distinct security advantages (once you have a file opened, nobody can truly take it away from you as you have a lock on the inode or equivalent). POSIX systems handle this with the fstat() system call, available on all platforms Tcl supports except Windows.

However, on Windows the implementation of file stat (NativeStat() in tclWinFile.c) works by opening the file and then using GetFileInformationByHandle(). As we already have an open handle in the situation we are looking to support, using it with that call should be straight-forward.


For at least file handles opened on conventional files, there will be an additional read-only option that can be retrieved with chan configure: -stat. This will return a dictionary (same format as TIP #594 proposes returning) that contains the file information determined by the fstat() or GetFileInformationByHandle() system call (depending on platform) at the time that the call is performed. The option will not be available for the standard file channel type if the file does not have a native handle.

It will be undefined whether channels opened on other things will have that option, but if they do and are defined by Tcl, they must use the same format of value. (Third-party channels are not so constrained.)

It will be the responsibility of the caller to flush channels prior to calling if they believe that doing so will make a significant difference to the results.

This entails no public C API changes.

Other Options

I considered creating chan stat channel, but thought that that has the disadvantage of requiring every channel type to consider adding the functionality when it only really makes sense for files (and file-like things) opened on the native filesystem. (For example, it makes no sense at all for files stored in a mounted zip file.)

This option would require extending the channel API at the C level, and consequently would be quite a bit more work.


This document is placed in public domain.